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Introduction 

Limit Of Liability 

While every precaution has been taken to ensure the correctness of the software and 
its accompanying manual, Micol Systems Inc. cannot assume any responsibility or 
liability for any damage or loss caused by our software. It is the responsibility of the 
user to make the necessary backups for the data and programs, 

Apple Computer, Inc. makes no warranties, either express or implied, 
regarding the enclosed computer software package^ its merchantability or Its 
fitness for each particular purpose. The exclusion of implied warranties is not 
permitted by some states. The above exclusion may not apply to you. This 
warranty provides you with specific legal rights. There may be other rights 
that you may have which vary from state to state. 

GS/OS is a copyrighted program of Apple Computer, Inc. licensed to Micol 
Systems Inc. to distribute for use only in combination with Micol Advanced 
BASIC (GS version)* Apple software shall not be copied onto another diskette 
(except for archival piirposes) or into memory unless as part of the execution 
of Micol Advanced BASIC. When Micol Advanced BASIC (GS version) has 
completed execution^ Apple software shall not be used in any other program. 

Product Revision 

Micol Systems Inc. reserves the right to make improvements to this software and 
manual at any time without notice. 

The text jQle INFO.DOC on the /MAB.SUPPORT disk contains the latest 
information about this product which could not be included in the manual at the time of 
publication. Be sure to read this file into the editor for up-to-date information. 

Copyright Notice 

This technical manual and the related software contained on the diskettes are 
copyrighted materials. All rights reserved. 

Duphcation of any of the above described materials for other than personal use of the 
purchaser, without express written permission of Micol Systems Inc., is a violation of the 
copyright laws of the United States and Canada, and is subject to both civil and criminal 
prosecution, 

Apple, the Apple logo, Apple IIGS, AppleShare, Image Writer, LaserWriter, Apple 3.5, 
Finder, GS/OS, QuickDraw and UniDisk are trademarks of Apple Computer, Inc, 

Micol BASIC, Micol Advanced BASIC, Micol Advanced Utilities and Micol MACRO 
are trademarks of Micol Systems Inc. Micol BASIC, Micol Advanced BASIC, the Micol 
Advanced Utilities and Micol MACRO are copjnrighted programs of Micol Systems Inc. 
Micol Systems Inc. is an independent software developer. 
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Chapter One: General Review 1 

Part One: Overview of the Language 

Chapter One 

General Review 

Comments on the Second Edition 

We are proud to present the Second Edition of the Micol Advanced BASIC for the 
Apple IIGS reference manual. This manual has been completely reorganized to make it 
easier for everyone, especially the novice, to use. 

If you are one of those who owns a First Edition copy of the manual, take the time to 
carefiilly look at the table of contents and the index to see where the changes were made. 
The table of contents and the index have been greatly expanded to make it easier for you 
to find the information you are looking for. 

Take the time to read the manual through. You will find many programming tips 
written by people who have discovered and are already enjoying the power of the Micol 
Advanced BASIC Structured Language. 

This reference manual has program examples throughout the entire manual. We 
recomm^end you study these program examples very carefully. You may also wish to 
compile and execute some of the more important ones. This way the explanations will 
become clearer to you and you wUl get practice in programming. 

Send us your suggestions, comments and criticisms. We read all the letters we 
receive, even if we cannot reply to all of them. We will answer you if you include a 
self-addressed envelope with your letter. 

Overview 

The purpose of Part One is to give an overall look at Micol Advanced BASIC so you 
will get a general idea of what this language system has to ofier. 

Micol Advanced BASIC is a fLill -featured, compiled language system. Its purpose is 
to let you develop structured BASIC language programs for your Apple IIGS. 

The BASIC program is created using the fuU-screen editor. Communication with the 
GS/OS operating system is done by means of the Command Shell. The Compiler and 
Linker translate BASIC source code into binary instructions which the microprocessor 
can directly execute* 

Some Advantages of the Language 

Micol Advanced BASIC needs only 768K of random-access memory to function, and 
yet all its components (the Command Shell, the Editor, the Compiler/Linker, and the 
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Run-Time Library) remain in memory during development. While developing your 
programs, no long delay will occur for one of the components to be loaded from disk. 

The executable load files created by Micol Advanced BASIC use a special fast load 
format and may only be loaded by the loading software supphed with this product, 

Micol Advanced BASIC may be used to produce Classic Desk Accessory files just by 
uBing a utility program provided. Stand-alone Micol Advanced BASIC programs use a 
common library located in a specific folder on the stand-alone disk. 

A Stand-alone Micol Advanced BASIC program may also be executed on an Apple 
IIGS connected to an AppleShare network. Micol Advanced BASIC can also produce 
S16 (OMF) files that may be launched with the GS Finder. 

Source code files created with the Ile/IIc version o£ Micol Advanced BASIC are highly 
compatible with those created with the GS version; only a few changes are needed to use 
the fall power of the IIGS version. 

Micol Advanced BASIC can use all the memory available to your Apple IIGS and is 
written in assembly language, the fastest code possible on your computer. Little time is 
spent compiling or linking, giving you more time do to what you can do best... program. 

The Components of the Language System 

1. The Command SheU 

The Command Shell (or Shell, for short) allows the user to interface with the rest of 
the language system. Through the Shell, for example, it is possible to see the contents of 
a disk, invoke the text editor, compile a program, etc» 

The Shell also has the capabihty of accepting commands from a file on disk. Utilities 
written by the user may also be added to the Shell. Because of these utilities, the 
possibilities of tasks the Shell can perform are almost unlimited. The Shell has the 
following features: 

Easy to remember commands 

Full complement of filing commands 

Testofcompi^ d programs 

• Commands executed ia a Shell Batch program 

• AutoExec batch file 

• Uses commands written in BASIC 
Easy- to-read help screen. 

2. The Source Code Editor 

The Source Code Editor lets you create, and modify BASIC source code files. The 
editor has word-processor-Hke features to ease the maintenance and revision of the 
source code files. The editor can read standard TXT ($04) or SRC ($B0) type files. The 
editor has the following features: 
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SO-columii, full-screen editor 

128 kilobyte biiJEfer (large enough for a file with about 4000 lines of code) 

Word-processor- like commands 

Fast and easy copy/movement of text 

Saves source code files in normal ASCII format 

Decimal to hex (and back) converter 

Easy-to-read help screen 

3. The Full-featured Compiler and Linker 

The Compiler reads the source code created using the source code Editor and 
generates an object code file which the Linker will convert to a machine usable format. 
The Compiler has the following featin^s: 

Rapidly generates 65816 code 

Uses FastLoad to bring programs into memory fast » 

Easy-to- remember Compiler Directives 

Ultra fast screen displays 

Support of source code Hbraries 

Link to assembly language programs 

Easy creation of large programs 

Easy creation of startup disk 

Utihty to create Classic Desk Accessories 

4. Full-featured Structured BASIC Language 

With Micol Advanced BASICy you can write programs that are more understandable 
than almost any other BASIC language. The use of meaningful variable names, 
indentation, structxired loop control, improved data file handling, and many other 
features will make the creation of yoxir programs a breeze. Now you can write those 
GOTOless programs that were impossible to do under Applesoft BASIC, 

Micol Advanced BASIC can produce graphics and sounds that could never have been 
done before on an Apple II using Applesoft BASIC. Both Super High Resolution graphic 
modes (320 X 200 and 640 X 200) are supported with graphic text- capabihty. Micol 
Advanced BASIC can also play back digitized noise, music or speech. 

Micol Advanced BASIC gives you the abihty to easily create apphcations that exploit 
multiple Windows and pull down Menus made famous with the Apple Macintosh"^'^ 
computer. The Micol Advanced BASIC language systems offers the following features: 

• Upward compatible with the Applesoft BASIC language 
Optional line numbers 

• Dynamic character strings up to 1023 characters 

• Simple variables and arrays of type boolean 
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Ultra fast and sophisticated string manipulation 

True integer calculations (no conversion to real and back) 

Calozlationg of extended values: both integer and real 

MouseText character display 

INKEYS input and PRINT USING output 

IF..THEN..ELSE, CASE^OF conditional statements 

REPEAT..UNTIL, WHILE.,WEND conditional loops 

Pascal language-like Functions and Procedures 

Support of recursive calls 

Low and Super High Resolution graphics 

Mixed text and graphics 

Great sound capabilities 

Complete and easy-to-use GS/OS file handling 

SuperTrace™ debugging command 

Easy Desktop program definition 

Complete and easy use of the Apple IIGrS Toolbox 

Exclusive Controlled Uncertainty*^^ 

How this Manual is Organized 

This manual is divided into eight distinct parts: 

• First is the Copyright pages and Table of Contents. We have taken pains to 
make this Table of Contents as useful as possible. We hope you agree. 
Part One (this part) gives you a general overview ofMicol Advanced BASIC 
(MABX and how to use Micol Advanced BASIC with the usual equipment There 
is a brief tutorial in Chapter Two all beginners should try. 

Part Two discusses the Programming Environment; what is needed to write and 
use a Micol Advanced BASIC program: Shell, Editor, Compiler/Linker, Library. 

• ■ Part Three is the most important section and describes the Micol Advanced 

BASIC language itself. 

Part Four describes the Desktop commands and some guidelines on how to write 
a Desktop'based program. This section should be ignored by beginning 
programmers as it is quiet involved. 

• Part Five discusses the Apple IIGS ToolBox and how to access it firom Micol 
Advanced BASIC. This section shoiild be ignored by beginning programmers. 
Part Six discusses program management. Management includes debugging 
techniques, code segmentation, code optimization, and using assembly language 
routines with jour Micol Advanced BASIC programs. 

Last come the Appendices, Glossary of words and Index. The Index is very 
complete, so if you have trouble finding something, feel free to consult it. 
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Special Note 



Special paragraphs marked Trograininers", "NOTE*', 
"IMPORTA]Nrr, and "WARNING" wiU be contained 
within a paragraph such as this one. These paragraphs 
describe tricks of the trade, indicate some special things 
to watch out for or alert you to a potential dangerous 
situation, "Programiuers'* denotes advanced topics that 
novices may ignore. 



The Micvl Advanced BASIC System Disks 

You have received with this product: 

• The Micol Advanced BASIC GS Reference Manual, Second Edition 
One system disk labeled Master Disk. 

• One system support disk labeled /MAB .SUPPORT 
A product registration card 

• Information about the Micol Advanced BASIC Users Group (MABug) 
Other Product information 

The first disk labeled Master Disk contains the Micol Advanced BASIC language 
system itself The second disk labeled /MAB. SUPPORT holds folders containing 
example programs, utihties, tool sets> fonts, devices drivers, etc, normally txnused with 
Micol Advanced BASIC, 



IMPORTANT 



Please make backup copies of both system disks before 
starting your program development. Use the copied 
disks for your work and store the original disks 
somewhere safe. 



The Micol Advanced BASIC language system consists essentially of four files 
(contained in folder MICOL.ADV,BASIC on the disk labeled Master Disk) and the 
Utilities folden COMPILER SHELL, EDITOR, LIBRARY, MICOL.ADV,BASIC and 
UTILITY/ folder COMPILER.SHELL is the integrated Compiler, SheU and Linker 
EDITOR is the source code Editor, LIBRARY is the run time Library and 
MICOL. AD V.BASIC is the Micol Loader, necessary to load stand-alone Micol Advanced 
BASIC programs. 

The UTILITY folder will contain the external Shell commands you may write later 
to add more functionality to the Command Shell. The file AutoExec will tell you about 
any updates to the Language System or the Reference Manual. 

The MAB,SUPPORT disk contains the following folders/files: 
folder Demo.PUes 
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• folder MAB.T0,S16 (see Part Six, Chapter Five) 

• folder MAB.TO.CDA (see Part Six, Chapter Five) 

• folder SYSTEM (contains GS/OS files not needed in Micol Advanced BASIC) 
an optional text file named INFO, DOC 



IMPORTANT 



The Demo.Files folder contains the source code of 
numerous example programs that could be very helpful in 
your imderstanding of this lan^age. It is very important 
you look at these j51es in some detail. The fractal 
mountain generator is in the Fractal. Samples folder 
under the name Mt.Fractal. There is also a very nice 
demonstration game written in Micol Advanced BASIC in 
the folder MABug.DEMO (read the READ.ME file). 



File INFO.DOC contains the latest product mformation which is not contained in 
this manual. If this file is absent, the manual is complete. 

Micol Advanced BASIC also uses the Apple IIGS Ibols in the proper folder. The 
other files or folders are used by the (jS/OS operating system which Micol Advanced 
BASIC uses to communicate with yotir hardware. 

What You Need to Know 

Before you continue reading this manual, you should know: 

How to set up and use your Apple IIGS system (see the manuals that came with 
your computer) 

Some knowledge and understanding of the ProDOS file structure and use of 
Pathnames to access these files 

How to use (^/OS to manipulate disk files (see the Apple IIGS System Software 
User^s Guide) 

Some knowledge of Applesoft BASIC or any other dialect of BASIC 

Advanced programmers should know about the Toolbox of the Apple IIGS. 

Hardware Requirements 

To use Micol Advanced BASIC for the Apple IIGS, you need one of the following 
computer systems: 

• An Apple IIGS with ROM 01 (or later) and a minimum of 768K of RAM 

• An Apple He with GS Upgrade and ROM 01 and a minimum of 768K of RAM 

With: 
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One 3.5 inch disk drive 

A monochrome monitor capable of displaying 80 columns 

GS/OS, the DOS required by Micol Advanced BASICy is supplied on disk. 

Suggested Additional Hardware 

A printer 

More memory on the expansion card (see below) 

A second or more disk drives 

• A hard disk drive 

• A color monitor 

Run Time Memory Needs of Stand Alone Applications 

^ Text only application: 512 kilobytes 

Text aad picture files: , 768 kilobytes 

Text and animated graphics 768 kilobytes 

Text, pictures, and sound files 768 kilobjrtes 

Graphic text and picture files 768 kilobytes 

Graphic text and animated graphics 2048 kilobytes 

Graphic text, animated graphics, and sound files 2048 kilobytes 

Simple Desktop programs (15-35K without Library) 768 kilobytes 

Regular size Desktop programs (36-50K without Library) 1024 kilobytes 

The amoxmt of memory may vary depending on the size of the program, the numbers 
of arrays, picture files, sound files, etc. 

Setting up Micol Advanced BASIC on a Hard Drive 

1. Boot a GS/OS System Disk which brings you into the GS Finder. The Finder has 
the facilities for this task. 

2. Create a subdirectory called MicoLAdv,BASIC under the volume directory of your 
hard disk (choose New Folder under the File Menu or press <Apple>N). 

3. Copy the Micol Advanced BASIC system files : 

a) Copy the ffles MICOKADV.BASIC, COMPILEKSHELL, EDITOR, LIBRARY, 
and the UTILITY folder fix)m the Master Disk (folder MicoLAdv.BASIC) to the 
subdirectory Micol J^dv.B ASIC you just created on your hard disk. Lock these 
files. 

b) Copy the file MicoLIcons fi:^m the Master Disk to the ICONS folder of yoxu- hard 
drive, 

4. Put the original Micol Advanced BASIC disks away in your archive box. 



Part One: Overview of the Language 



8 



Chapter One: General Review 



Using Micol Advanced BASIC with the Finder 

1. Open the Micol JVdv^BASIC folder by clicking on it twice or by clicking once and 
pressing Apple-O to open the folder. 

2. Drag the Micol.Adv,BASIC icon onto the Desktop, Close the folder and Window. 
Dragging the icon onto the Desktop allows easier access to MAB. 

3. Start the Micol Advanced BASIC language system by quickly clicking twice on the 
MicoLAdv.BASIC icon or by clicking once and pressing Apple-0 to open the 
program. 

Using Micol Advanced BASIC With a RAM Disk 

Micol Advanced BASIC recognizes the RAM card created by the RAM Disk option of 
the Control Panel. 

If Micol Advanced BASIC for the Apple IIGS detects a RAM disk with at least 192K 
of free space, it will use this RAM disk for its scratch work for compiling and linking. If 
there is no such RAM disk, the scratch work will be performed where the final linked 
program is created. 



WARNING 



l£ Micol Advanced BASIC detects a RAM disk with a free 
space greater than 192K, it will use this RAM disk for its 
scratch files. These files axe normally deleted at the end 
of compilation and/or Unking. However, if an operating 
system error should happen during compilation or 
linking, these jSles will not be deleted. You should then 
delete these files yourself manually from the Shell, 
otherwise this RAM disk may not be used again. 



Use of a RAM disk is highly recommended as it greatly speeds up the program 
development cycle: edit, compile/link, (execute), correct. 

Using Micol Advanced BASIC With Your Printer 



Micol Advanced BASIC allows you complete access to the Control Panel of the Apple 
IIGS, If you used the Control Panel's Printer or Modem Port controls to configure your 
printer, the printer should function properly because Micol Advanced BASIC uses the 
settings of the Control Panel. Refer to your Apple IIGS Owner's Manual to see how to 
change the settings. 
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Cortfiguring Your Printer Using the Control Panel 

You may use the Control Panel while working with Micol Advanced BASIC to alter 
the panels parameters. These parameters work with the built-in serial port or with a 
printer interface in the proper slot with the slot setting to *Tour Card'*. 

Because of the natiire of laser printers, Micol Advanced BASIC will not work with 
them. If you are using the Network Version of Micol Advanced BASIC, the program 
output may be printed using the network spooler. 



WARNING 



Some third party printers may need a device driver in the 
directory Drivers/; otherwise the printer may not function 
correctly. See your printer's manual if you are uncertain. 



If You Need Assistance 

Four good rules to follow are: 

1. Don't panic. Take a deep breath and relax for a minute, 

2, Go through the following checkHst to delimit the problem 

a) See if you computer meets the minimum hardware requirements (see Hardware 
Requirements) 

b) Make certain that your hardware and peripherals are connected correctly and 
that all connections are secure. If a particular peripheral needs a device 
driver, make sure that it is installed on the boot disk 

c) Get your reference manual and consiilt 

— the Table of Contents and/or Index 

— find and read carefully the sections pertinent to your problem. More than 
sixty percent of all calls for technical support can be answered simply by 
reading the manual. 

3, Ask a friend who has a computer to come and help you. Your friend may have 
enough experience to explain what you do not understand 

4. Contact \xs at Micol Systems. You can communicate with us by mail or by phone. 
We provide free technical support to our registered custom^ers: 

a) By mail, write to Micol Systems Inc. 9 Lynch Road, Willowdalej Ontario 
CANADA M2J 2V6, We will answer your letter by mail if you include a 
self-addressed envelope 

— Please include: a description of yoxir hardware (computer brand and model, 
size of memory on expansion card), and the list of the peripherals in the 
computer 

— a complete hsting (preferably on disk) of the program causing the problem. 
Determine where the problem is and clearly mark its location. If this is 
not done, we cannot help you. 
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b) By phone, call otir office at (416) 495-6864. You caa reach us during normal 
business hours Monday to Friday, 9:00 AM to 5:00 PM Eastern Time. There 
is no fee to pay except for the long distaace call, if applicable. Sorry, we 
cannot accept collect calls- 

Compatibility Overview 
Applesoft BASIC 

Micol Advanced BASIC is not a simple compiler of Applesoft BASIC programs and 
should not be thought of as such; it is much more than that. However, since Micol 
Advanced BASIC is a language system based upon Applesoft BASIC, you may convert 
your Applesoft BASIC programs to Micol Advanced BASIC programs with very httle 
effort. Most programs written under Applesoft BASIC will run under Micol Advanced 
BASIC with modest changes. Please see Chapter Six, Part Six for more information. 

You will have to modify the portions of code using: 

Disk filing 

Graphics 

Machine language routines 

Special memory locations (PEEKs and POKEs) 

Error handling 

Program, segmentation 

By making additional changes, you may take advantage of additional memory for 
programs or data, create better graphics and sounds, etc, 

Micol Advanced BASIC for the Apple Ile/IIc 

Micol Advanced BASIC for the Apple He and Apple lie source code files are highly 
compatible with Micol Advanced BASIC for the Apple IIGS, You may use the same 
source files. Since you have a much greater programming space, you should be able ^ 
add the features you want in your programs. 

You will have to modify the portions of code using: 

Graphics and Sound 
Machine language routines 
■ Special memory locations (PEEKs and POKEs) 
Error handling 
Program segmentation 



NOTE 



Programs developed \inder the Apple Ile/c version must 
be recompiled under the Apple IIGS version. 
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Earlier Versions of MAB for the Apple IIGS 

Most programs developed with Micol Advanced BASIC GS v2,0 to v3.7.2 are 
compatible with Micol Advanced BASIC v4.0. You may use the same source code. Of 
course, all programs developed with an earlier version o£ Micol Advanced BASIC for the 
Apple IIGS must be recompiled to execute under Version 4.0 €£ Micol Advanced BASIC, 
Please note that there has been a major change to the WINDOW command Check 
Chapter Three, Part Four for details. 

Syntactic Symbols Used in this Manual 

Within this manual we will follow certain syntactic rules which you must know 
before reading this manual. The rules are: 

Brackets [ ] are used when something is optional. - , 

NOTE: Brackets are used in the syntax of some statements. 

Braces { } are used to indicate that something is optional and may be repeated. 

NOTE: Braces are also used to delimit comments. 

Bold capital letters are used whenever a reserved word is denoted 

Aexpr is used to denote an arithmetic expression either integer or real An Aexpr 
may simply consist of an integer or real variable. 

Alop is used to denote an arithmetic operator. An arithmetic operator may be a + - * 
/^MOD. 

Relop means a relational operator. A Relop is a: <, >, <>, >=, <=, = and may also 
include the logical operators: AND, OR, NOT 

Sexpr is used to denote a string expression. An Sexpr may simply be a string 
variable. 

Expr is used to denote any expression, integer, string or real. In short, an Expr is an 
Aexpr or Sexpr. 

Identifier is used to denote a Fxmction, Routine, Procedure, Program or variable 
name. An identifier is made of letters, digits, undersc -re, ampersand, dollar sign, 
percent sign to a maximimi of 62 characters. 

Letters are either uppercase or lowercase and are case insensitive (no distinction is 
made between A and a). 

Unop is a unary logical operator. It may be a plus sign, minus sign and NOT 
operator 

Filename is a string of alpha- numeric characters no longer than 15 characters in 
length. 

Volume name is a string of alpha-numeric characters no longer than 15 characters 
in length. A slash {/) precedes the actual name. 

Pathname is a string made of a volume name, directories (if any) and a file name. It 
may be no longer than 64 characters in length including slashes. 
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Chapter Two 

Getting Started 
A Brief History of BASIC 

The original BASIC was written in 1964 under the direction of John Kenemy and 
Thomas Kin-tz at Dartmouth College, New Hampshire, United States of America. 

BASIC is the acronym for Beginners All-purpose Sjanbohc Instruction Code. It was 
intended to be relatively easy to learn and iaexpensive to implement The original 
BASIC was an interactive language, so that the programmer would get instant results. 
BASIC was originally intended as a teaching tool, so its capabilities were very limited. 

Originally, a program line in a typical BASIC program had to begin with a line 
number. Subsequent implementations of the BASIC programing language required no 
line numbers and featured structured programming statements like REPEIAT.. UNTIL 
and WHILE..WEND. 

Applesoft BASIC was installed in the Apple 11+ computer in 1979 as the successor to 
the primitive Integer BASIC. Apple hadn't yet developed a disk operating system, so 
Applesoft had no built-in DOS commands, among many other limitations. 

Micol BASIC was released in 1985 by Micol Systems as a structured and compiled 
BASIC language system based on Applesoft BASIC. Micol BASIC was designed to run 
on an Apple II+, He (64K) and lie. Although Micol BASIC was much more powerful than 
Applesoft BASIC> it stiU was designed for a computer with limited abihties. 

Micol Systems entirely rewrote Micol BASIC for the Apple IIGS and added numerous 
enhancements and improvements which became Micol Advanced BASIC, version 1,0, for 
the Apple IIGS in 1988. The next year, a special version for the Apple He (128K), lie, 
and Laser 128 computers was released which took advantage of the better graphics and 
auxiliary memory in these computers and has most of the features found on the GS 
version. 

Writing Your First Frogram in Micol Advanced BASIC 

Okay, let's write a simple program in Micol Advanced BASIC. This program won't do 
much, but if 11 be a start. Just follow these simple steps: 

1. Insert a copy of the Micol Advanced BASIC system disk marked Master Disk into a 
3.5 inch drive, Ttim on the monitor and the computer. 

a) The GS/OS operating system (the program that tells the computer how to use 
the devices connected to the computer) will load and execute 

b) The Micol Advanced BASIC Language System will load and execute. The 
Command Shell prompt (}) will be displayed with the Command Shell waiting 
for a response firam the user. 

2. Enter HELP<CR> (<CR> means press the key marked Return). This command 
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lists all the commaada known to the ShelL Take the time to read the commands 
that are available. Enter HOME<CR> to remove the Shell's Help display. 

3. Insert a work disk into a drive: 

a) If you have a second disk drive, insert an already formatted disk with little or 
no information on it and go to step 4 

b) Remove the Micol Advanced BASIC (Master Disk) disk and insert an already 
formatted disk with little or no information on it. (The disk containing the 
sytem will not be needed for program development). 

4. Enter PREFIX /Name.of I>isk<CR>. Replace Name.of.Disk by the name you gave 
the disk when it was formatted, PREFIX tells the Shell to use the disk 
Name,of Disk as the default disk. The Command Shell does not care where the 
disk is, as long as (jS/OS can find it; otherwise the message "Volume not found" 
will be displayed- Unless otherwise instructed, the system always uses the 
"prefixed" disk To see which default directory the system is using, enter 
PREFIX<CR> without a disk name. To see the names of aU of the volimies 
available in the system, enter ONLINE<CR>. 

5. Enter EDIT<CR>. This Shell command will bring you into the Micol Advanced 
BASIC Source Code Editor, 

6. Press <Apple>H (hold down the key with the white apple on it and the H key at the 
same time). This command shows the commands known to the Micol Advanced 
BASIC Source Code Editor. Press any key to make this screen disappear. 

7. Enter the following program; be certain to press Return after each line. Press 
Delete to erase a character. Press the Arrow keys to move the cxirsor. Press Tab 
to make an indentation in a program Une, 

PROGRAM First_Prograin 

HOME 

INPUT "Hello, I'm your Apple JIGS, what's your name? "; Name$ 

PRINT ''Nice to meet you "; Name$ 

PRINT "Watch me count from one to ten" 

PRINT "But first, press any key so I can start" 

GET Any_Key$ 

FOR Count% = 1 TO 10 

PRINT Count% 
NEXT Count % 

PRINT '^Good-bye "; Name$; '\ I hope we meet again'' 
END 

Take the time to check and revise what you entered- 

8. Press <Apple>S to save the program to disk. The Editor prompts for a program 
name* Enter any name (letters only) of no more than eleven characters and 
press Return. The program will be saved to disk. 

9. Press <Apple>Q to quit the Editor and return to the Shell. 
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10, Enter CATALOG<CR>, The contents of the disk directory will be displayed on 
the screen. Notice the name of the file you just saved. 

11. To compile your program, enter the word COMPILE followed by a space, followed 
by the name you gave the program in step 8, followed by a Return. The 
Compiler will display "Compiling. ».<Progr am name>"- If you have entered the 
program correctly, your program will be transformed into a format that can be 
executed- If there is an error in the program, the message ''Continue 
compilation, Edit program, or use Shell (C/E/S)?" will be displayed on the screen. 
Press "E" to return to the Micol Advanced BASIC Source Code Editor and 
correct the mistake. Continue with Step 8. 

12, After the program has compiled without any errors, you will receive the message 
"Execute the program (Y/N)?**. Press "Y" to cause the program to load and 
execute, 

13. The program will ask you for your name. Enter your name followed by the Return 
key. Notice the action on the screen. That was all caused by the program you 
just wrote. 

When the program has finished execution, control will be returned to the Shell. 
Congratulations! You have written and executed your first Micol Advanced BASIC 
program. 

Entering Program Examples 

Some program examples within this manual cannot fit in the manual's page the 
same way they would appear on the screen. If you see the Program Line Continuation 
character, the backslash (\), this indicates that the remainder of the line is continued on 
the next line (you may also enter the program lines exactly as they appear in the text if 
you wish, the Compiler can handle this syntax). 

Example: 

PROGRAM Example 

HOKE 

INPUT ^Enter name: ";Name$ 

INPUT "Enter age: ";Age% 

INPUT "Enter any floating-point value: "; \ 

Numbers 
END 

Enter the line(s) containing a backslash as if the line(s) were continuous (do not 
enter the backslash, in this case). If the line has more than 80 characters, the Editor 
will follow you by scrolling the display from left to right. The Editor will reposition the 
display to its usual place when you press the Return key. 
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Suggested Manuals 

Apple Computer Inc., Apple IIGS TQolbox Reference Volume I, Reading, Mass.: 
Addison-Wesley Publishing Co., 1988. 776 p. 

Apple Computer Inc., Apple IIGS Tbolbox Reference Volume II> Reading, Mass.: 
Addison- Wesley Publishing Co,, 1988. 700 p. 

Apple Computer Inc., Apple IIGS Tbolbox Reference Volume III, Reading, Mass.: 
Addison- Wesley Publishing Co., 1988. 1100 p. 

Apple Computer Inc., Human Interface Guidelines, Reading, Mass.: Addison- Wesley 
Publishing Co., 1987. 160 p. (This is the book needed to write software that conforms to 
Apples guidelines.) 

Apple Computer Inc., Standard Apple Numerics Environment (SANE) Manual. 2nd 
ed., Reading, Mass.: Addison- Wesley PubUshing Co., 1988. 320 p. (This manual contains 
the details of other SANE functions that can be implemented in Micol Advanced 
BASIC.) 

Apple Computer Inc., GS/OS Reference Manual Vol. 1, Reading, Mass.: 
Addison- Wesley Publishing Co., 1990. 528 p. (This manual contains the details of other 
GS/OS calls that can be implemented in Micol Advanced BASIC.) 

Little, Gary B., Exploring the Apple IIGS, Reading, Mass.: Addison- Wesley, 1987. 552 
p_ (The examples in this book are written using APW macros.) 

Little, Gary B., Exploring Apple GS/OS and ProDOS 8, Reading, Mass.: 
Addison- Wesley PubUshing Co, 1988. 369P (we frequently use this book for reference), 

Gookin, Dan and Davis, Morgan, Mastering the Apple IIGS Toolbox, Greensboro, 
North Carolina,: Compute! Publications, Inc., 1987. 642 p. (outdated, but excellent for 
learning the Apple IIGS Tbolbox. This book appears to be out of print, but if you should 
find a store that still has one in stock, we recommend you buy it.) 
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Part Two: The Programming Environment 

Chapter One 

The Command Shell 
Overview 

The Corojoaaad Shell is the control program. Through the Shell, you can do basic disk 
filing, enter the Soiirce Code Editor or compile, Hnk and execute a program. The 
Command Shell performs a similar function to the ProDOS 8 command interpreter, file 
BASICSYSTEM, performs under Applesoft BASIC. 

The Right Brace character "]*• is the prompt character of the Shell. 

Line Editing Commands 

These commands allow you to edit the commands entered from the keyboard. 

Up and Down Arrow Keys (tJ.) 

The Up and Down Arrow Keys are not used in the Shell. 
Left and Right Arrow Keys (^<-) 

The Left and Right arrow keys will work only within the range of an input field. 

The Return key 

The key marked Return terminates a command and may be pressed anywhere in an 
input field without loss of characters. 

The Delete key 

The Shell recognizes two deletion modes, true delete and destructive backspace. By 
default, the Delete key performs a destructive backspace. lb toggle between the two 
deletion modes, press <Apple>Delete. 

The destructive backspace mode erases the character to the left of the cursor The 
true delete mode erases the character luader the cursor. All characters on the right of the 
ciu-sor are moved to the left. The shape of the cursor is not changed. 
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The delete mode will remain until it is modified by another <Apple>Delete or until 
the system is restarted. 

<Coiitrol>C (Break) 

Pressing <Control>C will terminate a listing of a text file started with the LIST 
command. 

<Control>C may also be used to iuterrupt the execution of a program while it is 
running. 

<Control>R (Repeat) 

Pressing <Control>R displays the last command executed. The command is not 
executed, but is displayed so it may be modified if necessary. Press Return to execute 
the command again. 

The Shell "remembers" the previous command, even after using the Editor. 

<Control>S (Space/Stop/Start) 

Pressing <Control>S inserts a space character at the current cursor position, moving 
every character after the cursor one position to the right. 

This command may also be used to stop and start a file listing or program execution, 
<Control>X (Cancel) 

Pressing <Control>X cancels the command being entered. A backslash character (\) 
appears as the last character on the line to indicate that the previous command has been 
cancelled. 

Bttilt-in Shell Commands 

These commands allow you to perform the basic tasks of the Command Shell- 
Additional Shell commands may be written using Micol Advanced BASIC. 

BATCH Pathname 

The BATCH command allows Shell commands to be read from a text file on disk and 
executed as though the commands were entered from the keyboard. The Pathname is 
the name of a text file in a directory currently online. 

The Batch file is usually created by the Source Code Editor^ and is simply a text file 
containing the Shell comm^ands described here which are to be executed by the 



Part Two: The Programming Environment 



Chapter One: The Command Shell 18 



Command ShelL The commands are displayed as they are executed. 

Any shell command except another BATCH command is a legitimate entry into a 
batch file. An EDIT or COMPILE command will execute, but will end the batch 
stream. 

Any line in the Batch file beginning with a semicolon (;) will be considered a 
comment, 

<Control>C will cancel the execution of a Batch file. 

BATCH is particularly helpful to users who are doing their program development on 
a RAM disk and wish to set up their system to their own needs. 

AutoExec File , " ^ 

When Micol Advanced BASIC is first booted, the system checks for a Batch file xinder 
the Micol Advanced BASIC folder called AutoExec. If this file is present, the Batch 
stream contained within AutoExec is executed, otherwise the system simply enters the 
Shell 

The system disk marked Master Disk has an AutoExec file on it, so you may wish to 
examine this file to better understand AutoExec files. 

Example: 

LIST INFO .DOC 

/Erase or renaine the AUTOEXEC file to stop 

; INFO. DOC from appearing again. 

The batch file AutoExec lists the INEO.DOC file on the screen. 

CATALOG [Pathname] 

CATALOG and its abbreviation CAT are used to display the contents of a volume or 
any of its directories. The directory information indicates if a file is locked or not, lists 
its name, type, size of the file in blocks, its date and time of creation, its date and time of 
modification and t^ e size of the file in bytes. The quantity of blocks used and unused are 
listed after the list of the contents. 

If a Pathname is stipulated, the directory will be read firom the stipulated volimie. If 
the Pathname does not begin with a slash (/), the default prefix will be used with the 
stipulated directory name. If a Pathname is not stipulated, the directory of the default 
prefix will be displayed 

Example: 

CAT /RAM6 

CATALOG SUBDIR/ 
CAT 
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COMPILE Pathname [, Pathname] 

This command invokes the Compiler. The first Pathname is the source code 
Pathname of the file you wish to compile* If the source code Pathname cannot be found, 
an error will occur and the Shell prompt will return. 

If the Pathname is followed by a comma and another Pathname, then the object code 
file will have this stipiilated pathname with the appropriate extension added. After the 
compilation is completed, the filename containing the compiled program win end with a 
^LNK" extension. 

If a sjrutax error is detected, the BASIC source code line will be displayed in inverse 
video. You will be prompted T>o you want to Continue, Edit or return to the Shell 
(C/E/S)?. To continue the compilation, press "C". The Compiler will continue the 
program's compilation, lb edit the error, press "E", The Editor will place the cursor on 
the line and approximate character where the compilation error occurred, lb retinni to 
the Shell, press "S". The prompt of the SheU will appear. 

COPY Pathnamel TO Pathname2 

COPY duplicates the contents of the file Pathnamel by creating a new file and 
giving it the name Pathname2. If the original file and the duplicate file are in the same 
directory, Pathnamel must be different firom Patlmame2, 

Example: 

COPY /Disk/01d*File TO /RAM5/New,File 

The file Old.Pile iq volume /Disk will be copied to volume /RAM5 with the name 
NewFUe. 

CREATE Pathname 

CREATE generates a new directory file (folder) under the main or a subdirectory 
with the name stipulated by Pathname, The directory created is locked. 

Examples: 

CREATE /RAM6/DIRECT.1 

CREATE /Library/Math/Trig 

In the first example, the subdirectory Direct. 1 will be created on volume /RAM6. In 
the second example, the subdirectory Trig will be created on volume /library in the 
subdirectory Math/. 

DELETE Pathname 

DELETE erases a file fi:-om a directory, A subdirectory file must be empty before it 
can be deleted. The disk must not be write protected and the file must be unlocked. 
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Example: 

DELETE /RAM6/Filename 

EDIT [Pathname] 

The EDIT command summons the Source Code Editor The stipulated file must be 
of type TXT ($04) or SRC ($B0) to be edited. 

If the command EDIT is entered without a Pathname and no file is being edited, the 
Editor will appear. No file name appears on the Data Line as there is ctirrently no file 
being edited. 

If EDIT is entered without a Pathname and a file is being edited, the Editor' will 
appear to let you continue the editing process. The cursor will appear in the identical 
line and position as when you last left the Editor. The Pathname of the file is displayed 
on the Data Line. 

If the EDIT command is followed by a Pathname and no file is being edited, or the 
file being edited has not been moodified since the last save, the stipulated file will be 
loaded from disk into the Editor's workspace. The file's Pathname will appear on the 
Data Line. 

If EDIT is followed by a Pathname and the file currently being edited has been 
modified without being saved, the Command Line of the Editor wiU prompt "Save 
current file before loading new one (Y/N)?". If *V is pressed, the file currently in the 
Editor will be saved to disk, the workspace will be emptied and the specified file will be 
brought into the editor. If "N" is pressed, the file currently in the Editor will be erased 
from the editor's worlispace and the specified file will be brought into the editor. 

Example: 

EDIT/RAM6/TXT.FILE 

FORMAT Volume^Name 

To initialize a storage device, ;ise the FORMAT command. The initialized device will 
have the name stipulated as Volimie_Name. 

When this command is invoked, the Shell displays the location and the names of all 
devices connected to the computer. Select the appropriate device with the Up and Down 
Arrow keys and press Return to display the GS/OS Formatting Dialog Box. 

Set the controls of the Dialog Box to "ProDOS" for the operating sjrstem (if necessary) 
and **800K 2:1" for the interleave. Press Return to start formatting the device. 

For optimum performance with the white UniDisk 3.5 drive only, use 800K 4:1 
interleave. 



WARNING 



Be very caref\il with the FORMAT command. Once 
FORMAT is executed, any valuable information 
contained within the medium will be lost. 
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Example: 

FOEyyiAT Work. Disk 

HELP 

HELP lists the built-in Shell commands available with a brief description. 
User-written Shell commands are not listed 

Example: 

BELP 

HOME 

HOME is simply used to erase the contents of the screen and place the cursor at the 
upper left corner. 

Example; 

HOME 

LIST Pathname 

LIST displays the specified soxirce file on the screen, so you may preview it without 
entering the source code editor. Only files of type TXT ($04) will be displayed. 

Pressing <Control>C ends the Hsting; pressing <Control>S pauses the Usting. 
Pressing any key after that will restart the scrolling of the listing. 

Example: 

LIST /RAJyie/lNFO.DOC 

LOCK Pathname 

LOCK protects a file from being deleted or modified. When a file is locked, an 
asterisk (*) precedes the file name when a directory is displayed. 

Example: 

LOCK /RAM6/FILE 

ONLINE 

ONLINE displays the nadies of all the block devices such as floppies, hard drivesj 
RAM drives and CD-ROM drives connected to the computer. ONLINE displays the 
names of the devices and the names of the volumes. 



Chapter One: The Command Shell 22 

Example: 

ONLINE 

PREFIX [Directory_Name] 

The command PREFIX indicates the path used by the system or sets a different 
default prefix- The default prefix contains part of the path leading to a specific file. 

The default prefix is the prefix that is used unless another path is specified. If the 
Master Disk is booted, at startup, the (default) prefix is set to 
/MicolJ^dv,BASIC/Micolj\dv^BASICA 

The names of the volumes or directory files must be fix)m online volttmes. If not, the 
previous prefix will remain in use. The error message "Volume not found'* will be 
displayed if the volume is not online^ 

If Directory_Name is preceded by a slash character {/), the prefix will be changed to 
this new volxime name. 

If Directory_Name is not preceded by a slash character, the current prefix will be 
used with the EHrectory^Name appended to form the path leading to the directory. 

Examples: 

PREFIX {Displays the current prefix} 

{Adds System/Desk. Aces/ to the current prefix} 

PREFIX System/Desk. Aces/ 

{Prefix becomes /Micol . Adv.BASIC/System/} 

PREFIX /Micol.Adv.BASIC/System 

PREFIX <[<] 

This PREFIX command lets you move back one or more levels within a path by 
adding one or more less than ssmabols (<) with no separating spaces. One less than 
symbol (<) equals one directory level. 

Use PREFIX with a Pathname to go "outside'' any subdirectory. 

Example 1: 

PREFIX < {Go baclc one level} 

PREFIX {Display the current prefix} 

PREFIX « {Go back two levels} 

Example 2: 

If the current default prefix is /VOLUME/FIRST/SECOND/THIRD/FOURTH/, the 
conmiand PREFIX « will^et the new default prefix to /VOLUME/FIRST/SECOND/. 
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PRINTER 

PRINTER sets the port or slot niimber through which the printer output of the 
Editor and Compiler will be sent. The slot number entered must be a digit in the range 
one through seven. 

The default output is set to slot/port one. 

Example: 
PRINTER 
Send output through which slot? (1-7)? 

QUIT [Pathname] 

Use QUrr to leave the Micol Advanced BASIC language system. If QUTT is not 
followed by a Pathname, you will be prompted: "Are you certain you want to quit (Y/N)?'*. 
If "N" is entered, this command will be ignored and the Command Shell prompt will 
return. If "V is pressed, control will be returned to the opcratiag system. Once you 
have entered "Y", you will leave Micol Advanced BASIC, 

If QUIT is used with a Pathname, that GS/OS application will load and execute. No 
prompt requesting you to confirm your choice wiU appear, so mai:e sure that the disk 
containing the program launcher is online; otherwise, you will receive an error 

Example: 
QUIT 
Are you certain you want to quit (Y/N) ? 



WARNING 



Some program selectors (the Finder included) require 
that the startup disk be online before the GS/OS 
application can successfully execute. Do not attempt to 
execute these files unless the startup disk is online, 
otherwise, the system will crash!! 



J£ Micol Advanced BASIC was already started using a program launcher, use QUTT 
without specifying an apphcation name. 

If you have only a siagle drive system, you may copy the Finder from the 
/MAB,SUPPORT disk to a RAM disk and access the Finder from the RAM disk with the 
Micol Advanced BASIC system disk in the drive. 

Example: 

QUIT /MAB. SUPPORT/ SYSTEM/FINDER 

If the second system disk, as well as the startup disk, is currently online^ the Finder 
will load and execute. 
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RENAME Pathnamel TO Patlmame2 

RENAME changes the name of a file, directory or volume. If the paths are on the 
same volimie, this command may even be used to move a file to another directory- lb 
rename, Pathnamel must be unlocked and Pathname2 must not already exist. 

Example: 

RENAME /RAJyi6/FILE TO /RAM6/NEWFILE 

RUN [Pathname] 

RUN [Pathname] loads and executes the compiled and linked program specified in 
Pathname. The Pathname is usually the name of the source file of the program (the 
".LNK" extension is added by RUN). 

The RUN command may he entered without the Pathname to reexecute the previous 
program. 

Whenever a program is RUN, the values of all booleans are set to false, numeric 
variables are set to and all string variables to empty before executing the first line of 
the program. 

Examples: 

RUN /MICOL, ADV. BASIC/MT. FRACTAL 

UNLOCK Pathname 

UNLOCK removes the protection on a file, so it may be modified, deleted or 
renamed. A space rather than an asterisk will precede the filename when the proper 
directory is displayed- 

Example: 

UNLOCK /RAM6/FILE 

Adding Your Own Commands to the Shell 

When the Command Shell receives a command it does not understand, it assimies 
the command is the name of a Utihty, a compiled Micol Advanced BASIC program, in 
the folder UTILITY directly under the Micol Advanced BASIC folder, and attempts to 
load and execute it. 

If there is no such program name in the Utility folder, the Shell will display the 
message "lUegal command line". This filename is treated as equivalent to a built-in 
Shell command. 
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How to Write a SheU UtiUty 

The first step in writing a Shell Utility is simply to write a Micol Advanced BASIC 
program, compile and link it. 

After your Shell utility program is thoroughly debugged, take the compiled code and 
use the RENAME command to give the utility a meaningful name (no extension is 
necessary). Copy the completed program into the folder UTILITY. 

To access this utihty from the Shell, just enter the name of the command exactly as it 
appears in folder UTILITY. 

Passing Parameters to the Utility 

Micol Advanced BASIC Utilities may accept parameters. This parameter is a string 
entered by the user after the Utility name when the Utility is invoked. This parameter 
may not contain any spaces because a space is also a delimiter within the Shell (there 
must be a space between the Utility name and the parameter on the command Une). 

Example (from SheU command line): 
Get_Help Help -File 

The optional parameter, a simple ASCII string ended by a carriage return, will be 
placed into a buffer terminated by a zero (without the <CR>), The address of this buffer 
will be placed into locations 212 - 214 in the usual LSB, MSB, Banlt format. To access 
this string, concatenate the values starting at the address contained in locations 212, 
213 and 214 using the CHR$ function untU a zero is detected 

Example: 

PROGRAM My_Utility 

Parain$ ^ '^" 

AddressS = PEEK (212) + 256 * PEEK(213) ^ 65536 * PEEK(214} 

REPEAT 

Numbers = PEEK (Address&) 

IF Numbers <> THEN BEGIN 

Parain$ = Param$ + CHR$ (Number^) 

ENDIF 

Adress& = Adressi + 1 
UNTIL Number& «» {Your utility code follows) 

The parameter may then be used within your Utihty program for any purpose you 
require. 

See the INDENTER program on the /MAB. SUPPORT disk for a reahstic example of 
a Utihty This program also is included as a Shell Utihty on the disk labeled Master 
Disk If you enter INDENTER<CR> from the Shell, this Utility will execute; you will 
then be able to get instructions on INDENTERs usage. 
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Chapter Two 

The Source Code Editor 

Overview 

This full-screeu Editor has word processor like features plus easy Compiler access 
and debugging assistance. The Editor has easy-to-remember, two-keystroke co mm ands 
that ease the entry and revision of the sovirce code. 

The Editor retains the current file even while using the Command Shell, compiling 
or executing the program. 

Entering and Quitting the Editor 
Entering the Editor (EDIT [Pathname]) 

lb summon the Editor, enter EDIT or EDIT Pathname at the Command Shell level. 
The Editor may also be entered by pressing "E" from the Compiler if an error is detected, 
or firom a program if a run time error occurs while executing a program. 

Quitting the Source Code Editor (<Apple>Q) 

To leave the Editor and return to the Shell, press <Apple>Q. If the file being edited 
has been modified since the last save> the Editor will beep when <Apple>Q is pressed. If 
you hear this beep, you may wish to reenter the Editor (simply enter EDIT<CR>) to save 
the file before continuing. 

Description of the Editor^s Display 

The screen display of the Editor consists of 24 lines. The Command Line is at the top 
of the screen. A reference ruler appears on the second line. Directly under the Reference 
Ruler is the Editing Display Area where your program will appear. At the bottom of the 
screen on Line 24 is the Data Line. 

The Command Line. 

The Command line displays prompts and messages when the Editor needs to get or 
return information. 

The Editor's Command Line uses the following keys to edit the input to a command: 
Left Arrow, Right Arrow, Delete, <Control>S, and <Control>X- 
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The Reference Ruler 

The second line displays a ruler This line may be used to align text within the 
screen. 

The Editing Display Area 

The Editing Display Area is a window that uses 21 lines of the screen to show the 
text being edited. When necessary, this window moves up and down and from side to 
side to show text that cannot be entirely displayed within one screen. 

The Data Line 

This inverse video line gives inforaiation about the text file being edited: 

Line Counter 

— This number represents the cursor's current line position in the text buffer. 
It is affected by up and down cursor movements and the Groto Line function 
(<Apple>G). 

Column Counter 

— Entering characters or moving the cursor left or right causes the column 
counter to increase or decrease between 1 and 254, 

Line Length 

— The Line Length counter shows the total number of characters in the 
current line. 

■ Pathname Indicator 

— This area has a Pathname in it only after an existing file is loaded or after 
a new file is saved to disk. The Pathname will be truncated to fit the 
display if it is too long, This Pathname display remains until a new file is 
loaded or the text buffer is emptied, 

Calendar/Clock Display 

— The date and time will be displayed on the lower right side of the screen. 
When a file is saved, the date and time are automa' ;ally stamped on the 
file's directory entry. 

The Sound Indicator 

The editor will beep when the wrong command key is pressed. 

Basic Editor Commands 
Control Command Keys 

These Control key commands allow editing on a single line of source code. 
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<Control>B Erase to start of line 

<Control>B deletes the portion of the Une from the cursor position to the beginning of 
the Hne, 

<Control>X Erase current line 

<Control>X deletes the line where the cursor is. 

<Control>Y Erase to end of line 

<Control>Y deletes the portion of the line from the cursor position to the end of the 
Hne. 

The Apple and Option keys 

The Apple key and the Option key are used in combination with aaother key to give 
commands to the Editor. Either the Apple or Option key plus the other key must be 
pressed at the same time for a command to be executed. 



NOTE 



The Apple key is also called Command or Open-Apple. 
The Option key is also called Closed-Apple. On the Apple 
IIGS Upgrade, the Option key is called Closed-Apple. In 
this manual, <Apple> will refer to the White Apple key 
and <Option> will refer to the Black Apple key. 



Escape key (Esc) 

The Esc key may be used to cancel most commands at any time. 

Return key 

When the Return key is pressed, the cursor moves down to the beginning of the next 
line and the file is shifted down one line. If the cursor is in the middle of the line, the 
part to the right and under the cursor will be moved to the next line. The left side of the 
hne will remain as it was. 

Deletion Mode (<Apple>Delete) 

The Editor recognizes two deletion modes: true delete and destructive backspace. Tb 
change the deletion mode, press <Apple>Delete, <Apple>Delete toggles from destructive 
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backspace to true delete. By default, the Delete key performs a destructive backspace. 

The destructive backspace mode erases the character to the left of the cursor. The 
true delete mode erases the character under the cursor. All characters on the right of the 
cursor are moved to the left. The shape of the cursor is not changed. Destructive 
Backspace mode is shown by a Caret symbol {^) on the command line. True Delete mode 
is indicated by a Less Than symbol (<) on the command line. The Deletion mode 
character is displayed at the left of the Copyright notice on the Command Line, 

The delete mode will remain until it is modified by another <Apple>Delete or until 
the system is restarted. 

Delete Key 

To delete a character, press the Delete key. The character will be erased and the Une 
will move to fill the blank. If the cursor is over a line with no characters, this line will be 
erased and the following lines will move up one line. If the cursor is at the end of a line 
in the True Delete mode, or at the beginning of a Une in Destructive Backspace mode, 
the previous and the current line will be merged and that section of the file will move up 
one hne. 

Help screen (<Apple>H or <Apple>?) 

Tb see a summary of the commands available to you, press <Apple>Shift-/ or 
<Apple>H. The contents of the Editing Display Area will be replaced by the list of Editor 
commands. To remove the help screen and resume editing, press a key. 

The key Help is supported on any ADB compatible extended keyboard. 

Enter/Overstrike Mode (<Apple>E) 

lb alter the edit mode, press <Apple>E. Pressing these keys changes from Enter to 
Overstrike mode. Overstrike writes over existing characters without inserting other 
characters; En^- r mode automatically inserts the character The default setting is Enter. 
Enter mode is indicated by a flashing inverse space, Overstrike mode is shown by a 
flashing underscore. 

Upper/LowerCase Mode (<Apple>X) 

<Apple>X allows the user to enter uppercase characters without having to press the 
Shift key even when the Caps Lock key is in the Up position. 

To activate this feature, press <Apple>X; the "C in the copyright symbol on the 
command line will change to a lower case "c". The upper/lowercase entry will be 
reversed fi:om what it was. To enter lowercase characters while using this feature, press 
the Shift key. To deactivate this feature, press <:Apple>X again. 
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Moving in the File 
Cursor Control ('Ti< — >) 

All arrow keys are functional. For any liae greater than 80 characters, any attempt 
to move the cursor past the right edge of the screen will cause the display to shift to the 
left. If the screen has been shifted left, any attempt to move the cursor past the left most 
position of the screen wiU cause the display to shift right. Upward and downward 
motions work in the regular manner. 

Think of the display as being an 80 column, 21 line window to the text file, with the 
cursor keys allowiag you to move an)rwhere you want within the file. 

When the cursor is moved up or down, you will eventually reach either the top or 
bottom of the screen display. When the cursor reaches the bottom, the file scrolls up. 
When the cursor reaches the top> the file scrolls down. 

Move Down one screen (<Apple>i) 
Move Up one screen (<Apple>T) 



<Apple>Down- Arrow (i) will move the cursor to the bottom of the screen, or if the 
cursor is already at the bottom of the screen, it will scroll the display one screen page (20 
lines) up. 

<Apple>Up -Arrow (T) will move the cursor to the top of the screen, or if the cursor is 
already at the top of the screen, it will scroU the display one screen page (20 Hnes) down. 



NOTE 



The screen scrolling commands may also be used while 
selecting a block of source code that will be moved, copied 
or deleted using the <Apple>C, <Apple>D or <Apple>M 
commands. 



The keys Page Up and Page Down are supported on any ADB compatible extended 
keyboard. 

Move To Beginning of Line (<Apple><-) 
Move To End of Line (<Apple>"4) 



<Apple> Left-Arrow (<— ) will move the cursor to the first character of the current line, 
scrolling the display to the right if necessary. <Apple>Right-Arrow (-^) wiU move the 
cursor one character past the end of the line, moving the display to the left if needed. 
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Move to Previous Word (<Option><-) 
Move to Next Word (<Option>-^) 



<Optioii> Left- Arrow (<—) moves the ciirsor to the first character of the previous word 
on the line, scrolling the display to the right if necessary, 

<Option> Right-Arrow (-^) moves the cursor to the first character of the next word on 
the current line, moving the display to the left if needed. 



NOTE 



Pressing the <Apple> key instead of the <Option> key 
will not enable this command. 



Relative Motion within the File 

(<Apple>l through <Apple>9) 

Because a program source code file grows larger with every line you enter, the Editor 
"separates'* the file into 9 parts. Each part is recalculated as jrou add lines to your file. 
Pressing <Apple> and a digit key will bring this "Velative^ portion of the file to the 
display window. 

lb move to the beginning of the file, press <Apple>l. Tb move to the middle of the 
file, press <Apple>5. To go to the end of the file, press <Apple>9, 

The keys Home and End are supported on any ADB compatible extended keyboard. 

Go to Program Line (<Apple>G) 

Tb move quickly to a specific sequential program Une, use <Apple>G: the Goto line 
command. The command line prompts for an input. Give a line number and press 
Return. The line will be displayed on the first line of the display. This command helps 
locate the errors signaled by the Compiler. 



WARNING 



Do not confuse the sequential program line numbers with 
the optional BASIC source code line numbers. The 
sequential program line numbers are created by the 
Editor and the Compiler and are in no way related to any 
Hne numbers the user may create. 



Setting Tab Stops (<Apple>Tab) 

To set tabulation positions, press <Apple>Tab. The current tabulation marks are 
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indicated by diamonds on the Command Line. The default tab settings are placed one 
every fifth position. Tab stops may be set only for the jSrst 80 columns. 

To set or delete tab stops, move to the desired position using the Right- arrow key 
(Left-arrow will move back to position one) and press the Tab key. The first Tab pressed 
will set the first position, the second pressed, the second tab position, and so on up to the 
80th column. Press Return to confirm the new tab settings. 

Tabbing (Tab key) 

Use the Tab key to indent your source code. Td tab to the next tabulation position, 
press the Tab key. The default tab settings are every fifth position and may be altered as 
desired by <Apple>Tab. If the cursor is past the current end of line, pressing Tab will 
expand the current line to one character less the required Tab position, then the cursor 
will move to the required position. 



NOTE 



If the next Tab stop is currentiy occupied by text, pressing 
the Tab key will simply reposition the cursor without 

indenting. 



Text Block Editing Commands 
Copy Text Block from Buffer (<Apple>C) 

This command is designed to copy a block of text firom the copy buffer to the text 
area. You must have first moved the required hnes to the copy buffer using the Move 
Block command (<Apple>M) described below, otherwise you will receive an erron Move 
the cursor to the line just after the position where you want to place the lines, then press 
<Apple>C, The lines will be copied from the copy buffer. You may copy a maximum of 
32,767 characters (32K). 

Delete Text Block from Code (<Apple>D) 

To delete a block of text, press <Apple>D. Then press the Down arrow key to "'mark" 
the lines to delete. The Up arrow key will unmark the lines. To confirm the deletion 
command, press the Retimi key The marked text will be deleted- 

This command operates on whole lines only: the Delete Block command cannot be 
used to remove a portion of a line. 
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WARNING 



The Editor cannot recover deleted text once this 
command is executed. Use the Move Tfext Block command 
(<Apple>M) instead if you wish a possible recovery later. 



Move Text Block to Buffer (<Apple>M) 

To move a block of text to the copy buffer for later copying, and optionally, to delete a 
block of text, press <Apple>M. To mark the lines to be moved, press the Down-arrow 
key. To unmark the lines, press the Up-arrow key. Press the Return key to move the 
marked text tP the copy biifier. You will then be prompted if you wish to delete the 
marked text. Accepted input is "Y" for yes and "N" for no* A copy of the moved text will 
remain in the copy bufifer until this command is used again or you leave the Text Editor. 

The keys F2, F3 and F4 are supported on any ADB compatible extended keyboard- 
Find/Replace Commands 

Backward Find/Replace (<Apple>B) 
Forward Find/Replace (<Apple>F) 



The Backward Search and Forward Search commands are used to quickly move the 
cursor to a specific word or to search for and replace that word. A search always begins 
at the current cursor position. 

These commands can search for a specific word or phrase (from 1 to 64 characters in 

length). 

If the occurrence(s) of the word you want to search for is near the beginning of the 
file, use <Apple>F (Forward Search and Replace). Use <Apple>l to start from the 
beginning of the file, if necessary* If the occurrence(s) of the word you want to search for 
is, near the end of the file, use <Apple>B (Backward Search and Replace), "^"^se <Apple>9 
to start from the end of the file, if necessary. 

We will use Forward Search (<Apple>F) in the examples (backward search works the 
same way). The Editor prompts: Torward search: Find which string?". Enter the word(s) 
to find, then press Return, The text must appear exactly as it appears in the source code. 

''Case sensitive search (Y/N)T. Press "IST to find all occurrences regardless of the 
case. Press *T" to find only occurrences having the same upper and lowercase pattern as 
the one entered for the search string, A case sensitive search will look for word(s) with 
the exact combination of upper aad lowercase letters that match the character string you 
are looking for. 

The prompt "Replace with" asks for the string that will replace the word(s) you are 
looking for. If you are looking for a word, not replacing it, press Return without entering 
anything; otherwise, enter the replacement string. 

Do an "Automatic replacement (Y/N)?" If T" is entered, aU matches wiU be replaced 
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without user intervention. If "^N^ is entered, the user will be prompted to confiim the 
replacement of each occurrence as it is foxind. 

If the Editor finds the word(s) you are looking for, it will show the occurrence in the 
center of the editing area displayed in inverse video. The editor wiU prompt if you want 
to "Continue the search (ByTF/Q) T. Tb continue the search forward, press "F", Tb 
continue the search backward, press "B". To quit the search, press "Q". 

Example: 

{ Looking for a function } 

Forward search; Find which string? FUNC 

{Any case pattern} 

Case sensitive search (Y/N)? N 

{No replacement} 

Replace with (Press Return) 

{Prompt for every occurrence? } 

Automatic replacement (Y/N) ? N 



WARNING 



Because this command may make extensive changes to 
your file, we recommend you save your file before using 
the automatic replacement feature. Until you are 
familiar with this feature, it is easy to make mistakes. 
Just reload the file to "undo"* all the changes, if it did not 
do what you wanted. 



Filing Commands 
New Source Code File (<Apple>N) 

Tb clear the text buffer and start anew press <Apple>N. You are prompted for 
confirmation. If you respond "Y", you will be as if you had just entered the Editor. 



WARNING 



Once this command is executed^ the text cannot be 
recovered unless it has been previously saved to disk. 



Insert Source File from Disk (<Apple>I) 

To insert or merge another text file into an already existing text file, move the cursor 
to the line preceding the insertion/merge position, then press <Apple>L You will be 
prompted for a Pathname. Enter the Pathname and press Return. If the file does not 
exist, you will be notified. The text will be read firom the disk one line at a time. Each 
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time a line is entered, the screen displays this new line- The cursor will remain on the 
hne it was on before the command was given. 



WARNING 



Never use <Apple>I to insert a file at the last Hne of the 
current file as Insert cannot be used to Append text. 
Create a dummy line as the last Hne and Insert to just 
before this Hne. 



Save, Kompile and Execute File (<Apple>K) 

This command will perform a Save (<Apple>S), compile, link and execute the file 
being edited without the operator's intervention as long as no compilation or linking 
error occurs. 

If a compilation error occurs, the process is stopped, and the Compiler prompts: 
"Continue Compilation, Edit file or Shell (C/E/S) ?". An "E" entered here wiU return the 
xiser to the Editor at the position where the error occurred, A '"C" will continue the 
compilation, and an "S" will take the user to the Shell* 

If a run time error occurs during execution of the program, you will be prompted 
whether or not you wish to reenter the Editor to fix the problem. A "Y^ will place the 
cursor at the line containing the error. An "N^ returns control to the Shell » 



IMPORTANT 



Regular use of this command is highly recommended as it 
greatly simplifies program development. 



Load Source Code File (<Apple>L) 

To load a text fiJe into the Editor, press <Apple>L. This will bring up the command 
prompt line allowing a ^1 character Pathname. Enter the Pathname and press Return 
to load the file. Loading a file into memory removes the previous file in the text buffer 
After the file has been loaded, the Editor will display the first 21 lines starting from line 
one. The hne and column coxmters will display one. The Pathname is shown on the data 
hne before the clock display* 

If you want to load a new file after having made changes to the current file, the 
Editor will prompt you to save the current file before loading the new file. 

If you try to load a file larger than the text biiffer can hold, the part which will not fit 
in the buffer will be cut 
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IMPORTANT 



The <Apple>L commaad does not erase the text contained 
within the copy buffer. Use this command to copy text 
from one file to another, if necessary. 



Save File as TXT type file (bit 7 on) (<Apple>S ) 

lb save to disk the program yon are cxirrently editing^ enter <Apple>S. This is the 
usual file save command. If you save to an already existing file> this file will be deleted 
first, then the new file will be saved in its place. 

The Save command "remembers" the last Pathname entered. To reuse this previous 
Pathname, simply press "Y" to the prompt.- The file saved with <Apple>S is of tyi>e TXT 
($04). 



WARNING 



The Compiler generates the object file from the file on the 
disk, not firom the Editor bxiffer, so be certain to save your 
file before you call up the Compiler. 



Save File as SRC Type File (bit 7 off) (<Apple>T ) 

<Apple>T saves the source code text file as an ASCII file. The file saved with 
<Apple>T is of type SRC ($B0). The text file created can be read by most 

word-processors. This command works the same way as <Apple>S. 

Printing Commands 
Print Source Code (<AppIe>P) 

lb output a program hsting to your printer, press <Apple>R The command line will 
prompt you for the Hue number to start printing. Enter any positive niunber. Simply 
pressing Return is a line one. The command line will prompt you again for the line 
number to stop printing. Enter the second line number, or simply press Return as this is 
an implied last Hne. The printing of the Listing will start immediately To print the 
entire file, press the Return key twice. The Esc key may be used to cancel a print in 
progess. 

Example; 

First Line: 100<CR> 
Last Line: 701<CR> 
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Text Window Printout (<Apple>W) 

To print the text appearing in the text window, press <Apple>W. This command is 
most useful when you want a quick printout of the Editing Display Area* 

The key F13 (Print Screen) is supported on any ADB compatible extended keyboard. 

To cancel the printout in progress, press the Esc key. 

Miscellaneous Conunands 
Convert Decimal to Hex (<Apple>#) 

To convert a decimal number to hexadecimal, press <Apple># (<Apple>Shift-3). The 
command line will prompt you for input* Enter the decimal number to be converted to 
hexadecimal and press the Return key. Only valid numeric (0-9) characters will be 
converted properly as no error checking is done. Press any key to restore the co mman d 

display. 

Convert Hex to Decimal (<Apple>#) 

To convert a base 16 number to base 10, press <Apple># (<Apple>Shift-3). The 
command line will prompt you for input Enter a dollar sign ($) as the first digit to 
indicate that a base 16 nmnber will be converted, then the base 16 number followed by 
the Return key. Only valid alphanumeric (0-9, A-F) characters will be converted 
properly. Press any key to restore the command display. 

Version Information (<Apple>V) 

By pressing <Apple>V, the Editor's Editing Display Area will clear and something 
hke the following display will appear: 

GS/OS Version 3-3 

Micol Advanced BASIC GS version 4,0 

Last Modification Date 1 March, 19 92 

Bytes free in editor 234 53 

Bytes available in copy buffer 10009 

Lines available for editing 2000 

The Editors' maximum buffer size is almost 128 kilobytes: enough for about 3800 to 
4000 lines of code. You may copy a maximum of 32,768 characters {32K) to the Editor's 
copy buffer. 
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Chapter Three 

The Compiler 

Overview 

The Micol Advanced BASIC Compiler is a one pass compiler.; it reads the source 
code only once while generating the object code. The Compiler translates the ASCII file 
containing your BASIC program into an intermediate code which can be linked^ then 
executed, 

This chapter is short, but don't assume any lack of importance to the Compiler 
because of this chapter's short length. This chapter is simply a brief overview. The 
Compiler is the heart of the language system. Part Three, the longest Part, is a 
description of the language the Compiler can accept and in many ways is a description of 
the Compiler. 

Invoking the Compiler 

You may invoke the Compiler by using the Shell command COMPILE or by 
<Apple>K (Kbmpile) in the Text Editor (please see the appropriate section for details). If 
you do not use <Apple>K fix)m the Editor, be certain to save your file before exiting the 
Editor as the Compiler works on the disk file, not the file in memory* 

Example One: 

{Default prefix is /Micol -Adv, BASIC/} 

COMPILE DISK.UTIL 

The file DISKUTBL will be compiled onto the volume MicoLAdvBASIC as file 
DISILUnLXPOf. 

Example Two: 

COMPILE DISK.UTIL, /RAM5/FILER 

The file DISKUTIL will be compiled as file FILER.LNK (a .LNK is always 
automatically appended) on volume RAM5. 



WARNING 



Never forget that four characters are always appended to 
the object filename during compilation. If the total 
number of characters in the object filename results in 
more than 15 characters, you will receive an, error at 
compilation time. To avoid this minor problem, always 
specify a source code filename of 11 characters or less. 
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Dxirmg compilation, the Compiler generates three scratch files for its work. These 
scratch files are; 

<PilenarQe.COD> the object code file 

<FileName,LIT> the file where literal constants are stored 

<PileName.LiN> the file where forward references are stored. 

The above three scratch files are then used by the Linker to create the executable 
load module, <FileName>,LNK 



WARNING 



As soon as the compilation and linking processes are 
completed, the three scratch files are deleted. If however, 
during compilation, you should receive a disk full 
message, it is because there is not enough storage for 
these scratch files as well as the other files on the disk. 
In this case, you will have to delete some files or direct 
compilation to another volume. 



NOTE 



Before the Compiler begins the compilation process, it 
checks for the existance of a RAM device with 192K free 
space or more. If such a device is detected, three scratch 
files are created: A.COD, AXIT and A.LN on this RAM 
disk instead of the three scratch fi.les described above. 
Compilation is nmdl quicker if the scratch work can be 
done to a RAM device instead of a permanent storage 
device- If you have the available memory (more than one 
megabyte), it is recommended you configure the Control 
Panel RAM Disk to at least 192K. 



Compiler Commands 

The Micol Advanced BASIC Compiler has three Control key commands that may be 
used while a program is being compiled. 

Aborting a Compilation 

Pressing <Control>C stops the compilation in progress; control is retinrned to the 
Command Shell If you use this command, you will probably notice several error 
messages generated by the Compiler Simply ignore these messages as the compilation 
was not completed. 
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Compiled Listings to the Screen 

If you press the letter "L" during compilation, the Compiler will send a compiled 
listing to the screen. This listing may be turned off by pressing the letter "L" again and 
may be paused by pressing <Control>S. Pressing any other letter will continue the 
compilation. This compiled listing is the same as that generated by the compiler option 
LIST described later in this manual. 

Compiled Listings to the Printer 

If you press the letter "P" during compilation, the compiled listing will be directed to 
your printer. This listing is the same as that sent to the screen described above. 



WARNING 



The printer must be online at the time of compilation. By 
default, the printer must be connected to slot one or the 
system may hang. This slot niunber may be altered by 
the Shell command PRINTER. 



Dealing with Syntax Errors 

Unlike the Applesoft BASIC iaterpreter, Micol Advanced BASIC has dozens of 
different error messages, only one of which is the dreaded "Syntax Error". When the 
Compiler cannot make sense of a particular statement, it will send to the screen, ia 
inverse video, the source code line as far as it could "understand** it, and relate what the 
Compiler "thinks"" is the problem. The Compiler is sometimes wrong, but it is more often 
correct. In any case, you easily should be able to determine the real cause of the problem 
by taking time to read the error message and the line of code carefully 

You may be tempted to ask, when the Compiler gives you a message like "M' 
expected in line <line nujrTiber>", that if the Compiler knows what to expect, then 
why doesn't it simply insert t^ ) character and continue? 

Do not attribute any intelligence to the Compiler. It is little more than a very 
sophisticated pattern matcher and code generator. Some compilers do insert the 
character they "think" is missiag, usually with very bad results. 

The problem is that the Compiler often does not know what is really expected. With 
the information the Compiler has at the time, it is usually correct about what is needed. 
But maybe the cause of this error happened earlier. 

For example, the programmer may have mistakenly entered a reserved word and 
used it as a variable name. The Compiler might expect a left parenthesis when what it 
actually foimd was an equal sign. If the Compiler had replaced the equal sign with a left 
parenthesis, the situation would be worse, not better 
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Code Generation 

As you probably know, the BASIC program you write ia really only a representation 
of tlte actual code tliat is executed by the computer. This is true whether your program 
is compiled as under Micol Advariced BASIC, or interpreted as under Applesoft BASIC* 

If you believe that Applesoft code you entered is what is actually executed, try this 
little experiment. Write a small program in Applesoft, then do a CAIX -151 to get into 
the machine language monitor. Begin looking at the code starting at location $801 (2049 
decimal). You will not recognize much; it is a special tokenized code. 

The Micol Advanced BASIC Compiler scans your code and writes assembly language 
code as it goes. This is true cf most (but not ail) compilers, 

With most language systems, code generation is regarded as a sort of black box. All 
you need to know is that a particular program will generate the necessary machine code 
to performs its task. You seldom get to see the code that is generated; you have to look 
upon it as a sort of magic. 

Micol Systems takes a different approach. We believe that if you can see the code 
generated, you will better be able to understand what is going on and therefore write 
more efficient programSc 

In order to speed compilation and save disk space, the Compiler writes an 
abbreviated assembly language code to disk. If you were to look at the file 
<FileName>.COD file generated by the Compiler, you would not recognize very much, 
even if you knew 65816 assembly language. However, if you specify the CODE compiler 
option at the top of your program, the Compiler will display this code in an assembly 
language format (see Part Three, Chapter One for additional information). 

You will need a basic understanding of 65816 assembly language to understand this 
code, but as most of the detailed work of the compiled program is done by the run time 
Library routines, you won't need very much. 

Most of the generated code is either setting encoded addresses and calling Library 
routines to perform the task, or generatiag code to control the flow of the program. 
Because of CPU hmitations, most of the work performed by your programs must be 
performed by the Library routines. 

Man^' Library routines used by the compiled program faU into one of three 
catagones: integer, real or stiing. The Compiler generates subroutine calls according to 
the following criteria: if the Compiler recognizes an operation to be integer, it appends 
an "r to the function name stem. If it recognizes real arithmetic, it appends an "R", and 
it appends an ""S" for string routines. If the Library routine R+ is being called, for 
example, real addition is being performed. Some important library routines are; 

LNOtTT Saves the line number information 

MVARY Used with array manipulations 

FASS Places FOR loop counter values onto its stack 

FOR FOR loop controls 

NEXT Decrements the FOR variable stack pointer 

LDAC Gets the boolean result from the stack 
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Chapter Four 

The Linker 
Overview 

The Micol Advanced BASIC Linker will be summoned automatically if no error is 
detected during compilation- Because of this, the task of the Linker is mostly 
transparent to the user. 

After the source code file has been compiled, the program is still not yet ready for 
execution. Three intermediate code files were created by the Compiler. These files 
contain all the information the Linker needs to generate the executable module. 

The Linker will read files created by the Compiler from the volume where these files 
were written and create the file FileName.LNK in the appropriate folder. 

How the Linker Works 

First, the Linker reads the jump table (PileName,LN) that contains the names and 
relative addresses of all Functions, Procedures, Routines and other possible forward 
references in the source code. 

Second, the Linker creates the binary load module FileName.LNK by reading the 
FileName.COD file. The Linker replaces the references to all the names of the 
Functions, Procedures, Routines and internally generated labels with their addresses, 
and generates the necessary code as it goes. The Linker sends a period to the screen for 
every 250 lines of code it has processed. 

Third, after the generation of the executable code, the Linker converts the literal 
values written in the file FileName.LIT into binary and places this code at the top of the 
executable code module. These values will be loaded into their proper locations at 
initiaHzation time (when the program is first executed). 

After the linking process, the Linker will then try to delete the three scratch files 
generated by the compiler and used by the Linker, as they are no longer needed. 

How to Use the Linker 

As was already mentioned, the Linker is invoked automatically by the Compiler. The 
Thinker does, however, require some user input after its task is finished. 

If the Linker was summoned via the Shell using the COMPILE command, and the 

link is successful, you will receive the prompt, "Execute the file (Y/N)?^. If you enter "Y", 
the program will load and execute. If you enter "N", you will be taken to the Shell. 

If the Linker was called via the Editor with the Kompile (<Apple>K) command, the 
Linker will automatically load and run the executable object file after a successful link 
process. 
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Linking Errors 

When the Linker detects elh error, usually a non-existent Function, Procedure or 
Routine caU (FN Module.Id or GOSUB Module.Id), the Linker displays TTndefined 
subroutine <rD>" in inverse video. <ID> refers to the name used to define the Function, 
Procedure or Routine in the program. 

You are prompted to fix the error in the editor, 'TEdit the linker error (Y/N)?". A "Y" 
response to the prompt will bring the Editor to the screen with your file waiting to be 
edited. If you enter "IST, you will be taken to the Shell. 

Because the Linker does not know at which line the error occurred, the cursor is 
placed at the beginning of the source code file. Use the Forward Find/Replace command 
(<Apple>P) to locate the module call with the %ndefined^ subroutine <ID>. 
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Chapter Five 

The Rtm Time Library 
Reference Section 

The nm time Library^ file LIBRARY on the system disk, is the workhorse of the 
compiled program. The Library contains all the routines needed by the compiled code to 
accomplish its tasks. The functions performed by the run time Library may be anjrthmg 
firom doing integer multiplication to string garbage collection. The Library uses the 
floating point math routines of the Standard Apple Nxmierics Environment (SANE) 
contained in the Apple IIGS Toolbox as well as the Toolbox's graphics and sound 
capabihties, etc. 

The run time Library is brought into memory when Micol Advanced BASIC is booted 
and remains in memory until you leave the language system. As is the case with the 
Compiler, the Editor and the executable load modules you will create under Micol 
Advanced BASIC, the Library is relocatable. This means the Library is loaded where 
the GS Memory Manager teUs the Micol Loader memory is available. The Library is 
then referenced within a program by a jump location that is set at a fixed address in 
memory ($E100F0). 

The Library consists of scores of nm time routines and buffer memory. It comprises 
about sixty-four thoxisand bytes of code. Because most of the work the Library performs 
is done by internal routines, the speed of these routines is greatly increased. 

The Micol Systems Licensing Agreement 

The purchaser oi Micol Advanced BASIC has the right to make backup copies of the 
Micol Advanced BASIC software for his/her one personal use. This software may not be 
given to another party except with express written permission of Micol Systems. 

The piuxhaser of Micol Advanced BASIC has the right to make and distribute copies 
of the Micol Advanced BASIC Program Loader, the Micol ^wons, and the Rxm Time 
Library to execute a program developed by the legal owner of the Micol Advanced BASIC 
Language System if one of the two specifications below is followed. The Micol icons, the 
run time Library and the Micol System Loader (files MicoUcons, LIBRARY and 
MicoLAdv^BASIC) consist of copyrighted code belonging to Micol Systems Inc. 

That person or commercial entity owning a legal (non-pirated) copy of Micol 
Advanced BASIC is hereby granted a hcense to distribute free of charge compiled Micol 
Advanced BASIC programs provided one of the two conditions below is followed: 

1. The Micol Systems Copyright notice is displayed while Micol Advanced BASIC is 
booting, 

2. A negotiable, one time fee is paid to us before the release of the product on the 
commercial market. Once this fee is paid to us, you will receive a copy of a 
"Commercial Distribution License'' fiim us to use the Run Time Library, the 
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Micol Icons, as well as the Micol Sj^tems Loader whicli does not display the 
Micol Advanced BASIC Cop3nright notice, to be used with a specific product. 



IMPORTANT 



You do not have the right to ujse the Micol icons, the Micol 
Advanced BASIC Run Time Library or the Micol 
Advanced BASIC System Loader with a program 
intended for commercial purposes unless you have met 
one of these two conditions. 



Educational and Industrial Site Licenses 

Micol Systems Inc. offers to companies and school districts and boards the possibility 
of making unlimited copies of Micol Advanced BASIC by purchasing a site license. 

The site license package consists of: 

• The Micol Advanced BASIC disks: Master Disk and /MAB.SUPPORT. These 
disks contain special, fully networkable versions of Micol Advanced BASIC, not 
otherwise obtainable 

Two copies of the Micol Advanced BASIC reference manual 
A site hcensing agreement which allows you legally to make unlimited copies of 
the system disks and manuals for use with the specified site 
A product registration card 
The right to piirchase additional manuals at a reasonable cost, 

IXstrict and Board licenses are also available. For further details, contact the Micol 
Systems office during regular business hours. 
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Part Three: The Advanced BASIC Language 

Chapter One 

Compiler Rules and Directives 
Overview 

This chapter describes the general rules for writing Micol Advanced BASIC 
programs. You must pay special attention to this section as ttiere is nothing in Applesoft 
of a similar nature. This chapter also describes special features of the language that can 
greatly aid you in your program development 

General Information 

The programs you create with the Micol Advanced BASIC cannot be as fi^ee form as 
those created with Applesoft BASIC. You must follow certain rules regarding the 
sequential order of certain statements. This is something inherent to compiled 
languages. 

A Micol Advanced BASIC program consists of a series of program lines. Each 
program line consists of one or more program statements. A program hne may have a 
maximum of 250 characters and must end with a carriage return, 

Multiple Statements per Line 

A colon may be used to separate two or more program statements on the same line. 
Try to avoid this usage as it hinders program clarity. 

Example: 

TEXT 1 HOME 

Line Numbers 

If you wish, you may precede each program Une with a line number as under 
Applesoft BASIC. Line numbers may range between 1 and 65535. 
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IMPORTANT 



Line numbers are NOT required by Micol Advanced 
BASIC and their use is NOT recommended. Line 
numbers are no longer useful, and were retained solely 
for compatibility with Applesoft BASIC. Unless line 
numbers are referenced within a program, they wiQ be 
ignored. Use of line nximbers within a program is entirely 
up to the programmer, 



IMPORTANT 



When the Compiler or run time routine refers to a Kne in 
your program, it is referring to sequential line numbers 
given to the source code by Micol Advanced BASIC, not to 
any line numbers you have specified in your program. 



Program Line Contiauatioii Character (\) 

The Editor and Compiler accept source code lines up to 250 characters long. The 
Editor^s display will scroll from left to right when a source line of more than 80 
characters is entered, lb keep the program line within one screen, you may divide a 
source code line into two or more parts by terminating the line with a backslash (\), 
Enter the remaining source code line anywhere on the next hne. 

The backslash (\) must be the last character on the line and may appear only where 
extra spaces could appear. It may not be used to break reserved words or identifiers- 
The backslash may not be repeated on the same line, or you will receive an error. 

Example: 

PROGRAiyi Math 

HOME 

Number% - (1 * 6) + \ 

(2 * 5) 
PRraT Nuiiiber% 
END 

Commenting Your Programs 

Micol Advanced BASIC provides two ways to help you document a program: 

comment statements and comment delimiters- 
Use annotations to better understand what the program does in order to make 

changes, corrections, or add new features to the program at a later time* 
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NOTE 



Unlike Applesoft BASIC, Micol Advanced BASIC does not 
generate any code for the comments in a program (except 
perhaps for hne number information). Write whatever 
comments which aid in the understanding of the 
program. 



Comment Statement (Old Method) 

The REM (for remark) keyword instructs the Compiler to ignore all characters until 
the beginning of the next Une. REIM provides compatibility for programs originally 
written in Applesoft BASIC. 

Example: 

R£M You may write comments like this as in Applesoft, 
REM but the method described next is much better. 

Comment Delimiter Characters [{ )] (Preferred Method) 

Comments may also be enclosed within brace brackets [{ }], which may be placed 
anywhere in a program where extra spaces could be written. These comments may cover 
mxiltiple hues if you wish. 



NOTE 



Comment delimiter characters may be nested. An 
annotated section of code may be "commented out" 
without having to worry about the comments already 
written. "^Commented out" code is treated like any other 
comment. 



WARNING 



The right brace bracket (}) closes the comment and is 
extremely important. Do not forget to terminate the 
comjnent with a right brace bracket [}]; otherwise, the 
rest of the program will be considered a comment. 



Examples: 

PROGRAM Show_Comments 
{This is a comment 

covering a couple of lines} 
HOME 
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{{This FOR loop will not be in the program} 
FOR Counter% {Comment here too} = 1 TO 100 

PRINT Counter% 
NEXT Counter%} 
END {Show_Comments } 

Program Order 

A Micol Advanced BASIC program must begin with a program name. Compiler 
options are the next statements to be included, if needed. ALIASes, then DATA 
statements are declared thereafter. The optional identifier's type declaration follows 
next- Array declaration statements round up the program declarations. 

Except for the program name, the lines just mentioned are optional, but if compiler 
directives, DATA statements or array declarations are used, they must not appear out of 
the order mentioned above^ otherwise Compiler errors will arise. 

Example: 

PROGRAM Definition {Program Identifier} 

{Compiler Options} 

8 LIST, EXTEND 

ALIAS ^UNTIL 1*0''- "FOREVER" 

DATA 1, 1.0, ^n" {DATA statements} 

{ Identifier' s Type Declaration} 

INT (I - N> : STR (S - Z) 

DIM Alpha% (2), Beta (3), Coma$ (4) {Array declarations} 

{Actual Program Start} 

END 

Program Name 

The first line of each program must begin with the reserved word PROGRAM 
followed by a program identifier. The name of the program must begin with a letter and 
may only consist of letters (A-Z), digits (0-9) and underscores O^ and may not be a 
reserved word. 

This Une is not optional. If it is left out, the Compiler will return an error. 

Note that a period (.) is not allowed in a program identifier. 

Examples: 

PROGRAM First_Program 

PROGRAM Test -file {Not Allowed} 
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Compiler Directives 

Compiler directives are special commands given to the Compiler to tell it to do a 
special task, such as sending a listing to the printer. Compiler directives consist of both 
compiler options such as LIST, and other instructions to the Compiler such as ALIAS, 

The fact that the Compiler must see all the code before any program can be executed 
allows It to do certain things an interpreter is incapable of doing, such as giving more 
precise syntactic error messages. A thorough knowledge of these directives will help to 
get the most out of the compiled language and make programming more enjoyable. 

Compiler Options 

To use one or more compUer options, the line must begin with an at sign (@) followed 
by one or more options separated by commas (,). The compiler options may appear on 
separate liaes, but the lines must be consecutive. 

Example: 

PROGRAM Example 
@ LIST, CODE 
<Prograin Code> 

BANKING = Integer.Uteral 

This option is used to increase the memory allocated at run time for the string buffer 
and will probably only be necessary if you have very large string arrays. 

The memory is reserved in memory banks of 64K. By default, a program has one 
bank for its string storage. Under most circumstances, one bank should be sufficient. 

BANK_NO accepts integer values between 1 and 15, This means that as httle as 
one bank (64K), or as much as 15 banks (just over a megabyte) may be allocated for 
string storage. If the computer does not have enough memory for the number of banks 
specified, there will be an error when the program begins to execute, not when it is 
compiled. 

At the end of compilation, the Compiler indicates how many banks of memory for 
string buffer storage will be allocated for the program. 

Example: 

PROGRAM Example 
BANK_NO = 4 

In the example above, the program will allocate four banks (256K) of RAM for string 
buffer storage, 

CODE 

This option lets you see how assembly language code is generated by the Compiler as 
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it processes the program. Assembly language programmers will be able to see the code 
generated, and may be able to write better programs. CODE is included for the benefit 
of those who have an interest in leanoing more about how a compiler generates code. 

To see the code generation displayed to the output device, use the CODE option. The 
Compiler writes the object code to disk in a compact assembly language-Hke format. 
With this option, the code will be expanded on the current output device to look like true 
assembly language. 

Example: 

PROGRAM Example 
LIST, CODE 

HOME 
END 

The Compiler produces this code for this simple program: 

2 [0] $0000 HOME 

JSL LIBRARY 
BYT INIT 
BYT 00 
WOR 0000 
BYT 00 
WOR 0000 
JSL LIBRARY 
BYT HOME 

3 [0 ] 100 $0010 END 

JSL LIBRARY 
BYT LNOUT 
BYT 00 
WOR 0003 
JSL LIBRARY 
BYT END 

ERROR 

If a RESUME is used in a program which causes it to continue execution at the same 
line where a run time error occurred, the ERROR compiler option must have been 
specified to make the program function properly. 

This option causes the Compiler to generate six (6) extra bytes of code for each line or 
loop. If you are short of memory, don't use it. 



Part Three: The Advanced BASIC Language 



Chapter One: Compiler Rules and Directives 52 



NOTE 



ONERR GOTO branches wiU work without this compiler 
option, but the program will not be able to RESUME 
execution. 



See also the RESUME command in Part Three, Chapter Fourteen. 

Example: 

PROGRAM Example 
& ERROR 
<Prograin Cocie> 

EXTEND 

Use this compiler option to increase the range and accuracy of all real simple 
variables and arrays from 7 or 8 places to 19 or 20 places. This is especially useful in 
scientific or technical programs in fields such as microbiology, engineering, and 
astronomy. 

Normally, four bytes of memory are allocated for each real simple variable or real 
array element, but if the EXTEND compiler option is used, ten bytes of memory will be 
allocated for each real variable or array element. Each real value will have an accuracy 
to 19 or 20 places, with a range of ±10*^^^^^, Because floating point calculations are 
always carried out using extended arithmetic, there will be little difference in execution 
speed if this option is used. 

Example: 

PROGRAM Example 
@ Extend 
<Progi:am Code> 

LIST 

The LIST compiler option instructs the Compiler to generate a source code hsting as 
the program is being compiled. 

A compiled source code line consists of the sequential line number, the nesting level, 
the relative (not actual) address expressed in decimal notation where the first byte of 
this line will reside, this address expressed in hexadecimal notation, and the source code 
line. A symbol table dump of the variables followed by the memory usage information is 
displayed after the program lines. See "Compiled Listing^ later in this chapter for 
additional information. 

LONGINT 

Use this compiler option to increase the range of all integer variables and integer 
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arrays from five to ten places. If you are not using extended real numbers, the accuracy 
(but not range) of long integers is actually greater than that of real numbers, but their 
execution is much faster. This may be an important consideration for you. 

Two bytes of memory are normally reserved for each integer variable or integer array 
element. When the LONGINT compiler option is used, four bytes of memory are 
allocated for each integer variable or array element. Each integer value will have a 
range of ±2,147,483,647. 



NOTE 



Because integer arithmetic is very fast, there will 
probably be Little diflferenoe in execution speed if this 
option is used. However, twice as much memory is 
required for integer storage. This is only a factor if you 
have limited memory and very large integer arrays. 



Example: 

PROGRAM Example 
@ LONGINT, CODE 

NOGOTO 

This compiler option is intended for teachers who wish to restrict their students to 
structured programming without using GOTOs or POPs. By specifying this option, 
GOTO and POP statements will become illegal and cause a compiler error if used. The 
reserved words GOTO and POP may then be used as variable names. 

The ONERR GOTO statement is not affected by the NOGOTO compiler option. 

Example 

PROGRAM Example 
@ NOGOTO 

NOT^C 

This compiler option turns ofiF the <Control>C interrupt command abihty during 
program execution. Pressing <Control>C from the keyboard during a program's 
execution will have no effect on programs if this option is used- 
Example: 

PROGRAM Example 
@ NOT C 



IMPORTANT 



Do not use this compiler option until the program is 
thoroughly debugged. 



I 

I 
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OPTIMIZ 

The compiler normally generates line information to let the programmer know where 
a nm time error has occurred in the prograoiv 

This compiler option turns off the consecutive line information usually generated by 
the Compiler, This gives programs a small, but noticeable increase in execution speed. 
Use it to speed up the program once it is completely debugged* 



IMPORTANT 



The most important function of OPTIMIZ is to conserve 
memory. A program using OPTIMIZ is about one-third 

smaller than one without it. 



PRINTER 

This option functions the same way as the compiler option LIST, except output is 
directed to the printer instead of the screen. Output is directed through slot one unless 
changed by the Shell PRINTER command. The listing is printed according to values set 
in the Control Panel, 

Example: 

PROGRAM Example 
@ PRINTER 



VAR2 

This option restricts to two (or three if an exclamation mark (!), a dollar sign ($), an 
ampersand (&) or a percent sign {%) is at the end of the variable name) the number of 
significant characters in a variable name, as in Applesoft BASIC. 



NOTE 



Use this compiler option only if you are compiling source 
code files converted firom Applesoft BASIC programs and 
do not wish to modify the variable names. 



1 



Example: 

PROGRAM Example 
@ VAR2 
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Compiler Aliases 

ALIAS "User statement" = *^ASIC Expression^ 
-•User Statement 



The ALIAS compiler directive lets the programmer change a Micol Advanced BASIC 

statement or expression to another statement or expression of his/her choosing. 

ALIAS definitions are placed after the compiler options and before the variable type 

declarations. 

The purpose of Aliases is to give more meaning to your programs- For example, if 
you have a loop which you wish to execute as long as the computer is on, you may 
substitute Forever for the Micol Advanced BASIC code that actually creates this 
condition. 

An Ahas is defined by using the keyword ALIAS followed by the replacement 
statement, followed by an equal sign, followed by the statement that the Compiler will 
substitute. Both strings on either side of the equal sign must be enclosed in quotation 

marks ri 

To make the replacement within a program, use the tilde (--) character followed by 
the user replacement string (without the quotation marks). When the Compiler detects 
the tUde, it wiQ search the ALIAS list (created at the top of the program) for a match 
and make the replacement during compilation. 

An Alias substitution may not be the first executable line or the Compiler will issue 
an error. 



IMPORTANT 



All string Uterals used with Aliases are case sensitive; the 
Alias definition and user statements must exactly match, 
or no change will occur. No error will be flagged, but as 
no substitution will occur, an error condition will 

xmdoubtably arise when the line is complied. 



Example: 

PROGRAM Example 

ALIAS ^^Pi" = '"3.14159" 

ALIAS ''Forever" = ''UNTIL 1 = 2" 

ALIAS ^Clear Screen" = ^HOME" 

INT (A - Z) 

{Start of executable code follows) 

Trig_Const = --Pi 

-Clear Screen 

REPEAT 
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PRINT ""Trig^Const = ";Trig_Const 
"-Forever 
END 



NOTE 



If two Alias declarations beginning with the same letters 
are declared, the wrong match may be made. This 
problem may be avoided by declaring the longer Alias 
declaration first. 



Example: 

PROGRAM Example 

@ List 

{Note the order here, it's important, 

if reversed, only first Alias matched} 

ALIAS ^Pi_Long'' - ^3.14159" 

ALIAS ^Pi" = *'3.14" 

ALIAS ^Circumference" * ^^20-0" 

{Note! Order here is uniit^ortant } 

Diameter = -Circumference / --Pi 

Diameter = --Circumference / -Pi Long 



NOTE 



When the Compiler generates a compiled listing, the Alias 
substitution made during compilation will be displayed. 
If you are getting error messages that don't make sense to 
you, try generating a compiled listing. 



Variable Type Declarations 

INT( letterl-letter2 ) : STR( Ietter3-letter4 ) 

The variable type declaration allows the programjner to write the integer and string 
identifier's of simple and structured data types (simple variables and arrays) without the 
percent (%) or string ($) character reqxured by Applesoft; BASIC. These statements are 
optional and are placed before the arrays are declared. 

lb declare a range of variables, specify the data type (ENT for integer or STR for 
string) followed by a range of letters in parentheses. Separate the variable type 
declarations by a colon (:), 

The range of letters used for integer variables must be different firom the range used 
for string variables. If the declarations between the integer and string data types should 
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overlap, the Compiler will indicate that an error occurred 

Any possible implied declaration with the following characters, a *"%" for integer "*&" 
for real, "$" for string and "!** for boolean after the variable name, will override the 
declaration types mentioned above. These characters are still significant. Note that 
there is no impHcit declaration for booleans. 



NOTE 



A one letter range may be declared by specifying the same 
letter twice in the declaration* 



Example: 

PROGRAM Examplel 
INT (K-K) : SIR iS-S) 

Variables beginning with the letter K and having no special character at the end will 
be integer variables, while variables beginning with the letter S and having no special 
character at the end will be string variables. 

Example: 

INT (I-R> : STR (S-Z) 
First$ =- ''" 
Second = «" 
Seconds = ^^'" 
Second% - 
Third = "" 
Forth =0.0 
Ninth = 
Ninths =0.0 

First$ is a string variable 

Seconc^ s a string variable 

Second$ is a string variable different from Second 

Second% is an integer variable 

Third is a string variable 

Forth is a real variable 

Ninth is an integer variable 

NLnth& is a real variable 

In the above example, all variables which begin with letters A through H will be real 
variables (imless followed by the character !, % or $), All variables which begin with 
letters I through R will be integers (unless followed by the character &, ! or $), and all 
variables which begin with letters S through Z will be string variables (imless followed 
by the character &, % or !). Second and Second$, although string variables in the above 
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example, are different variables. 

Compiled Listing 

Whenever you use tlie LIST or PRINTER compiler options, you generate what is 
called a compiled listing. This compiled listing contains much infonnation that may be 
of use to you during your program development. 

Here is an exam^ple of a compiled Hsting: 

PROGRAM Example 

Compiled listing of Example 



3 


[0] 





soooo 


HOME 




4 


[0 ] 


16 


$0010 


FOR Counter == 1 TO 10 




5 


tl ] 


56 


$0038 


PRINT "Counter = 


"/Counter 


6 


[1 ] 


84 


$0054 


NEXT Counter 




7 


CO J 


100 


$0064 


END 





No errors in compilation 

SYMBOL TABLE DUMP 

1 R0205 10 R0209 Counter R0201 

530 bytes required for variable storage 
1 bank required for string storage 
118 bytes code generated 

Program Lines 

The first position in the program line is occupied by the sequential line number. 
This is the number that is used whenever a line is referenced. 

The second position in the program line is occupied by a number in square brackets 
([]). This number is the level of nesting in which the program line appears. For 
example, this nimiber tells you how many FOR loops or IF statements are currently 
active at the beginning of the line. This can be very valuable debugging information. 

The third value displayed is the relative address in decimal, followed by the relative 
address in hexadecimal, followed by the actual program hne itself 

Symbol Table Information 

After the program lines, the Compiler displays the Ust of all types of simple and 
structured variables xised in the program. 

The Symbol Table contains the relative hexadecimal addresses of all simple boolean, 
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integer, real and string variables, numeric constants (literals), and arrays. 

The capital letter in the address indicates the type of the variable, B indicates the 
address of a boolean, I indicates the address of an integer, R indicates the address of a 
real, and S indicates the address of a string 

The local simple variables (accessible only to Functions or Procedures) are the first 
variables Hsted in alphabetical order. The values assigned to simple and structured data 
types are Hsted second, also in alphabetical order. The simple and structured data types 
are listed third, also in alphabetical order. 

Dviring compilation, the names of all variables have been converted into uppercase 
letters and so appear in the Symbol Table* The name of a local simple variable is 
preceded by a number sign (#). An array name is followed by a left parenthesis [(], 

Statistical Information 

After the Syxabol Table has been displayed, there appear a few lines which give a bit 
of helpful information. These lines are: 

530 bytes reofuired for variable storage 
1 bank required for string storage 

118 bytes code generated 

The first line indicates how many bytes of memory were used by the boolean, integer, 
floating pointy and string variables and arrays, and all literals. The second line shows 
how many baiiks of memory are allocated for the string buffer. The third line shows how 
many bytes of program code were generated by the Compiler. 



NOTE 



The program will actually occupy a bit more memory than 
is specified by the last statistical information line. This is 
because some memory will be occupied by code generated 
by the Linker to store initialization ioformation. The first 
line of statisical information (bytes required for variable 
storage) will give you a rough idea of how much more. 
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Chapter Two 

Basic Elements of the Language 
Overview 

In order to understand any computer language, you first have to learn the basic 
elements comprising the language. This chapter will deal with these basic elements that 
you will need to build upon to create Micol Advanced BASIC programs. 

Basic Symbols 

Micol Advanced BASIC uses letters of the alphabet, digits, and special characters to 

form the symbols of the language. 

Digits (0 - 9) 

Digits are used to fonn numbers, keywords, identifiers, and character strings. 

Letters (A - Z, a - z) 

These characters are used to make keywords, identifiers and character strings. 

Special Characters 

These characters (!,©,$,%,&,_.,-(>){,)) may be used to give a specific meaning 
to identifiers, declare an array, specify a comment, etc. 

Separators 

Colon 

The colon (:) separates two statements on a line. 

Comma 

The comma {,) separates two or more constants or variables on a line. 
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Parentheses 

The parentheses [( )] separate complex string and math expressions as well as array 
element designators. 

Space 

A space specifies where one symbol ends and another symbol begins. 

Variable Names 

A variable name consists of letters, digits and the underscore character. A variable 
name may have up to 62 characters, but it is wise to limit its length to about 20 
characters or less. Unless the VAR2 compiler option is used, all characters are 

significant. 

The variable name must begin with a letter of the alphabet. Characters may be 
either in upper or lowercase, but lowercase letters will be converted to uppercase during 
compilation, 

A variable name may not be a reserved word and should be meaningfuL By 
convention, variable names are easily destinquished from reserved words in that 
reserved words are entered in uppercase letters while variable names are in lowercase 
with only the first character in uppercase. 

Unlike Applesoft, a variable name under Micol Advanced BASIC may contain a 
reserved word within it. For example Go^Home and For^Ctr are legal variable names. 

Examples: 

Factorial, General_Ledger, Tax, Price 

instead of variables Like 

213, XYZ, A123 

which are not meaningful. 

These variables are not legal: 

General. Ledger, 10%_Tax, Home 

Variable Data Types 

The data type defines the interpretation of values that simple variables, arrays, and 
expressions may have. Micol Advanced BASIC has four simple data types and four 
structured data types, one for each simple data type. 

Simple Data Types 

Micol Advanced BASIC supports boolean, integer, real and string variables as simple 
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data types. 

Booleans 

A boolean variable is assigned either a value of TRUE or FALSE, The function of a 
boolean variable is to be set to one state or the other, so that necessary action(s) may be 
taken later (this is often called a flag or switch). A boolean occupies only one byte of 
memory. The initial value of a boolean variable is FALSE. 

The normal convention for variable names applies, but an exclamation mark (!) must 
be added at the end of the variable name to force the Compiler to type the variable as 
boolean. 

Boolean variables may also hold an indefinite value if necessary. See Controlled 
Uncertainty in Chapter Twelve of this Part for details. 

Examples; 

Flag! - FALSE {Init flag for test} 
Number =10 

IF Number > 6 THEN Flag! = TRUE 
IF Flag! THEN BEGIN 

PRINT '^Number is greater than Six" 
ENDIF 



NOTE 



The keyword TRUE or FALSE is displayed to the current 
output device when a hoolean variable or relational 
expression is evaluated within a PRINT statement. 



Example: 

PRINT 1 <> 2 {Will print TRUE} 

Integers 

An integer value represents a numeric value that has no fractional part and has a 
limited range. The initial value of an iateger variable is 0. 

The normal convention for naming variables apphes, but a percent sign (%) must be 
added at the end of the identifier to force the Compiler to type the variable as integer 
unless an INT variable type declaration is in force. 

Example; 

Dividenci% - 1 

Divisor% = 3 

PRINT Divi<iend% / Divisor% {Result is 0} 
Micol Advanced BASIC for the Apple IIGS has two ranges for integer values: Short 
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Integer and Long Integer. 

Short Integers 

Micol Advanced BASIC can represent short integer values in the range ±32767. 
Negative values are represented as two's complement numbers. A short integer occupies 
two bytes of memory. 

Example: 

Short_Integer% = 32000 

Long Integers 

Micol Advanced BASIC can represent long integer values in the range 
±2,147,483>647, Negative values are represented as two's complement ninnbers, A long 
integer occupies four bytes of memory. 

Long integer arithmetic is activated with the compiler option LONGINT. See also 
Chapter One in this Part under Compiler Options, 

Example: 

Long_Integer% = 2146493697 

Real (Floating Point) 

A real number represents a value that can represent a large range of values and may 
have a fractional part. The default nimiber of significant digits that may accurately be 
represented is seven digits. The initial value of a floating point variable is 0.0. 

The normal convention for naming variables appHes, but an ampersand (&) may be 
added at the end of the identifier to force the Compiler to type the variable as a real to 
override an INT or STR variable type declaration. 

Examples:. 

Dividends = 1 

Divisors = 3 

PRINT Dividends / Divisors 

{Result is 0,3333333} 

Micol Advanced BASIC EKJS has two ranges of precision for floating-point numbers: 
Single and Extended- 
Single Precision 

Single precision reals can represent values in the range ±3.4 X 10^\ Seven digits 
are significant in calculations, A single precision real variable uses four (4) bytes of 
storage. 

Examples: 

PRINT EXPdoO) {Prints 2,718282} 
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PRINT EXP (2.0) {Prints 7.389056} 

Elxtended Precision 

Extended precision reals can represent values in the range ±1.0 X lu . Nineteen 
digits are significant in calculations. A real variable occupies 10 bytes of storage in 
memory. 

Extended precision arithmetic is activated with the compiler option EXTEND. See 
also Chapter One in this Part: Compiler Options. 

Examples: 

PRINT EXPCl.O) {Prints 2.71828182845904522} 
PRINT EXP(2,0) {Prints 7.38905609893065022} 

Scientific Notation 

Large real values that are too large to be represented in decimal format (more than 
seven digits using single precision) may be represented using scientific notation. 
Scientific notation representation uses a multiple of 10 raised to a power of 10. Values 
may either be set or displayed using scientific notation. 



Example 

Real 

Real& - 4E^6 



Real& = 4E6 (Equivalent to 4,000,000 or 4 k 10^} 



Strings 

A string is a sequence of characters including letters, digits, special characters, the 
space character and control characters. 

The normal convention for naming identifier appHes, but a dollar sign ($) must be 
added after the variable name to force the Compiler to type the variable as string. The 
doUar sign may be omitted if the STR Variable Type Declaration appHes to the variable 
identifier in question. 

The length of a string is equal to the number of characters inside it. Each string 
variable occupies three (3) bytes in data memory plus four (4) b3rtes of system 
information in addition to the characters in a separate string buffer The maximum size 
a string can grow is 1023 characters. However, a string literal can only have 251 
characters. 

Micol Advanced BASIC uses two types of string storage: static and dynamic storage. 

Static Storage 

Static strings are used when a string of characters is encased in double quotation 
marks ("") within a program* 
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Example: 

Name$ = ''Steve" 

Dynamic String Storage 

Dynamic string storage is used in all other cases, A dynamic string variable holds 
the address where the actual string is ia memory, but the actual string is stored in a 
special buffer area reserved for this purpose (see the compiler option BANKING for 
additional information). 

Structured Data Types: The Array 

Micol Advanced BASIC has four kinds of structured data types: Arrays of boolean, 
integer, real and string. 

Declaring Arrays 

DIM Array.Name [ !,%,&,$ ] (Size) \ 
[ {, Array_Name [ !,%,&,$ ] (Size) }] 

Arrays are always declared and dimensioned at the beginning of the program after 
the optional compiler options, the ALIAS declarations, and DATA statements. 

An array is a set of data of the same type. Each piece of information is called an 
element- Access to each element is made via a subscript (an index nximber to the array). 

The DEVI statement will allocate to the array the number of elements plus one, 
element beiag the first array element. 



NOTE 



Unlike Applesoft, all arrays, no matter how small, must 
be declared before they are used. If an array needs mor^ 
memory than is available to the computer, an "Out of 
memory^ error message will be displayed when the 
execution of the program begins, DIM sizes may only be 
nxmieric constants, not variables. 



lb declare an array, use the reserved word DIM, give the array any legal variable 
name followed by its size between parentheses, 

lb declare more than one array, separate each array name and size by a comma. 

Multi-dixnensional Arrays 

DIM Name [ I, %, &, $ 1 ( Size [ { , Size ) ] ) \ 
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[ , Name [!,%,&,$]( Size [ { , Size } ] ) ] 

A mvdti-dimeiisioiial array is aa array having two or more dimensions, A different 
size may be used for each dimension. 

lb add another dimension to an array, enter a comma followed by another size value 
after the first size dimension. To declare more than one array, separate each array name 
and size declaration by a comma 

Example: 

PROGRAM Month_Temp 

DATA 23, 34, 32, 12, 11, 22, 20 

DATA 18, 14, 17, 15, 16, 13, 12 

DATA 11, 10, 7, 3, 0, -3, -6, -14" 

DATA -17, "19, -15, -12, -10, -8 

DIM February (3, 6) 

HOME 

Temp_Total& = 

FOR Week = TO 3 
FOR Day - TO 6 

READ Teinperature% {Must read integer data} 
February (Week, Day) » Temperature% 
Teinp_Total& = Temp_Total& + February (Week, Day) 
NEXT Day 

NEXT Week 

Aver_Temp = Temp__Total& / 28 

PRINT '^The average temperature for February is: ";Aver_Temp 

END 

Although it is possible to have an array with more than three dimensions, it is rare 
that one has to use such arrays. Review the logic of the program if such a large array is 
required 

Array Memory Usage 

A boolean array uses one byte to hold the number of dimensions, two bytes per 
dimension size plus one byte times the number of elements plus one. 

An integer array uses one byte to hold the number of dimensions, two bytes per 
dimension size plus twice the nxmiber of elements plus two bytes (four times the number 
of elements plus four bytes, if the LONGINT option is used). 

A real array uses one byte to hold the nxmiber of dimensions, two bytes per 
dimension size plus four times the number of elements plus four bytes (ten times the 
number of elements plus ten bytes if the EXTEND option is used), 

A string array allocates one byte to hold the niunber of dimensions, two bytes per 
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dimension size plua three times the number of elements plus three bytes, 

Array Nesting 

Under most circumstances, integer index variables should be used with boolean, 
integer and string arrays; real index variables should be used with real variables to 
reduce array access time. 



WARNING 



If arrays are nested, that is, an array element is used as 
an array counter, you must nest arrays of the same type 
or an ferror will result. This means you may only nest 
real arrays within real arrays and integer arrays within 

string, integer and boolean arrays, 



Operators 

Micol Advanced BASIC has three types of operators: arithmetic, logical and 
relatioaaaL 

Arithmetic Operators 

Arithmetic operators are used with either integer or real variables. The arithmetic 
operators are addition (+), subtraction (-), multipUcation (*), division (/), exponentiation 
{^) and modulo (MOD). Here are some general rules to note: 

1. An overflow error will be indicated when the result of any calculation is over the 
allowed range for that variable type. 

2. Exponentiation works only with positive numbers; negative numbers will result in 
an error. Zero raised to any power is zero. Any positive number raised to the 
power of zero equals ie, 

3. The asterisk (*) is xised in many programming languages as the operator for 
multiplication to avoid confusion with the capital letter X 

4. The unary minus sign (-) indicates the change of sign when it is used with one 
operand. Unary plus (+) is redimdant and is ignored by the Compiler- 
Relational Operators 

A relational operator tests relationships between two conditions and produces a 
boolean result (TRUE or FALSE). It is this operation, more than anything else, that 
allows your programs to ""think^. 

The relational operators are: less than (<), less than or equal to (<=), equal to (=), not 
equal to (<>), greater than or equal to (>=) and greater than (>). 
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Logical Operators 

Logical operators operate on relational expressions to produce a boolean result of 
TRUE or FALSE. 

The logical operators are: NOT, AND, OR, 

Example: 

IF (Real < 5,3} AND (NOT (Integer% > 20}) THEN \ 
Flag! = TRUE 

Evaluation of an Expression: Precedence Rules 

The evaluation of an expression is done following a priority hst established by math 
conventions. If the priority of the expressions is equal, the evaluation is done from left to 
right. The established math priorities are as foUows: 



1. 


Expressions between parentheses 


() 


2. 


Unary operators 


-,+ 


3. 


Exponentiation operator 


A 


4. 


Miiltiplication, Division, and MOD operators 


♦/MOD 


5. 


Addition and Subtraction operators 


+ - 


6. 


Relational operators 


>, >=, <=, <, <> ,= 


7. 


AND logical operator 


AND 


8. 


OR logical operator 


OR 


9. 


NOT logical operator 


NOT 



You may wish to use parentheses to make certain an expression is evaluated in the 
intended order. An expression may contain any nvmiber of parentheses* 

Hexadecimal Literals 

A hexadecimal number may be assigned to any integer or real variable. A 
hexadecimal number is a base 16 number and is always preceded by a dollar sign ($) and 
consists of the digits through 9 and the letters A through R 

Example: 

Hex_Nuinber% = $12FF 

Real = $FFFFFF 

Mixed Arithmetie Expressions 

What dictates how the Compiler evaluates a line of code? Basically, the Compiler 
determines the type of calculation to perform by the first data type (real or integer) it 
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encounters in a statement, 

Micol Advanced BASIC handles mixed arithmetic very well, but extra code will need 
to be generated which requires extra time to execute. If possible, it is best to be 
consistent with yoxir variable types when coding. 

Expressions with Simple Variables 

Example: 

Real_Var& = Integer% * 3 + Reals 

Because this assignment is mad? to a real variable, the above formiJa will be treated 
as a real formula. The integer value in variable Integer% will be converted to real. 

Example: 

Integer% -• Reall& * Real25 / Real3& + Real4& 

In this example, each real value must be converted to its integer equivalent before 
the expression can be evaluated. It would be better to assign the formula to a real 
variable, then reassign the real variable to an integer variable in another statement. 

Example: 

Reals « Reall& * Real2& / Real3& + Real4& 
Integer% = Real& 

Expressions with Arrays 

As with simple variables, the Compiler determines the type of calculation by the first 
variable tyi)e it encoimters. What is different with arrays is that the array counter is 
also effected. It is best to maintain the same type of array and array counter. Integer 
arrays should have integer counters, and real arrays should have real counters. String 
and boolean arrays should use integer counters. 

Example: 

Arrays (Reals) * 3 

ArraY% (Int%) « Integer% 

Array$ (Int%) - '"String" 

Array! (Int%) - TRUE 

Any other choices from the above examples will force a 
conversion to the other type before the correct array element can 
be accessed. 

Simple Variable Declaration 

In Micol Advanced BASIC^ simple variables may be declared in one of two ways: 
impHcitly and explicitly. Implicit declarations are done simply by using the variable. 
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The Compiler determines whether a variable has not been used before and automatically 
allocates space for it if need be. This is the method used by Applesoft BASIC. 

Micol Advanced BASIC also offers the option of explicitly declaring a simple variable, 
similar to the way arrays are expHcitly declared. This means, you must state within 
your program, that you are using this particiJar variable. This is similar to the system 
used in Pascal and C. This method almost completely ehminates the possibility that you 
will later enter this variable incorrectly. 

ExpHdt variable declarations are also a very good idea for documentation purposes, 
as you can easily determine all variables used within the program. You may wish to 
include comments to better explain the variable's usage. 

Although the explicit declaration adds some complexity to the language, it is 
probably preferable to use imphcit declarations as program maintainance is made easier 

DECLARE Boolean!, Integer^, Real&, String$ 

To explicitly declare a variable, enter the reserved word DECLARE followed by a list 
of simple variables separated by commas. A program may have as many DECLARE 
statements as needed, but they must be the first and only statement on a program line. 



IMPORTANT 



If no DECLARE statement is encountered in the 
program, all simple variables will be placed automatically 
into the Symbol Table. Once a DECLARE statement is 
detected in the program, all subsequent variables, not 
already defined, must be declared by a DECLARE 
statement; otherwise, the Compiler will signal an error. 
If you attempt to DECLARE a variable a second time, 
you will receive an error at compile time. 



Example: 

PROGRAM Declaration 

DECLARE Real, Integer%, String? 

Reals =» 5.0 

Integer% « 25 

Strings ^ '^This variable has been declared" 

Any_Thing% - 23 (Error here, not in DECLARE list} 

Variable Assignments 

[LET] Avar = Aexpr 
[LET]Svar = Sexpr 
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The assignment instruction is the equal sign (=) and is used to assign an expression 
to a variahle- The equal sign also implicitly declares this variable if it has not been used 
before (if DECLARE is not being used). The expression is always located on the right 
side of the equal sign. The result is stored in the variable to the left of the equal sign. 

The reserved word LET may be used to specify an assignment* LET was retained 
solely for compatibility with Applesoft BASIC and is ignored by the Compiler. Use LET 
only if you wish to stay within the original definition of Dartmouth BASIC. 

Examples: 

Numbers =35.1 

Niainber% = 10 * 2 / 5 

String$ - ^This is a small message" 

Boolean! = TRUE 

Initializiiig the Data Space 



CLEAR 

CLEAR will reinitialize all simple and structured variables. All numeric variables 
will be set to zero, all strings will be set to empty and booleans will be set to FALSE as 
was the case when the program was first executed. 



Example: 

Variable = 10 
PRINT Variable 
CLEAR 

PRINT Variable 



{Value is 10} 



{Value is 0} 



WARNING 



An impUcit initialization is done at 'he first line of 
executable code. Branching to this line of code will reset 
all variables to zero or null as if the program restarted, 
Do not use CLEAR from any segment other then 
segment zero or you will crash the computer 
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Chapter Three 

Mathematical Functions 
Overview 

The mathematical fiinctions xmder Micol Advanced BASIC have been classified into 
two categories: general purpose functions and trigonometric functions, All use integer or 
real arguments and yield integer or real results. 

All calculations are made using single predsiou arithmetic unless the EXTEND 
and/or LONGINT compiler options are used (all examples use single precision). 

General Purpose Functions 
ABS (Aexpr) 

ABS (Absolute) returns the absolute (positve) value of the argument. The argument 
may be negative, zero or positive. 

Example: 

Number% = ABS (-10) 

PRINT Nuinber% {Will print 10} 

EXP (Aexpr) 

EXP (Exponent) yields the value of the constant e (2.718281828) raised to the power 
of the argument. An argument smaller than zero always retiuns zero. An argument of 
zero retxims one. 

Example: 

Exponent = EXP (10) 
PRINT Exponent 

INT (Aexpr) 

INT (for integer) returns the whole nimiber portion of the argument, discarding the 
fractional part, if any. 
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NOTE 



INT does not convert a real argTiment to an integer as the 
function name implies, but simply truncates the value. A 
real value remains a real value after INT has performed 
its work In Micol Advanced BASIC there are no 
functions to convert values firom real to integer and 
integer to real, but rather this conversion is done 
automatically and need not concern the user. 



Examples: 

Real_N-um& = INT (95,9) 

LOG (Aexpr) 

LOG (for logarithm) yields the natural logarithm base e (e = 2.718282) of the positive 
argument passed to it. If an argument equal to zero or negative is passed, a run time 
error will occur. 

Example: 

Logarithm =» LOG (10) 

MOD 

MOD (for modulo) returns the remainder of the real or integer division of the 

nominator by the denominator 

Example: 

Nominator% = 25 

Denominator% » 4 

Remainder% => Nominator% MOD Denoniinator% 

PRIN. Remainder% (Writes a 1} 

ROUND (Aexpr) 

ROUND returns the rounded value of the argument. For a positive value, if Aexpr is 
between x.5 to x.9, the residt is rounded upward. If the value is between x.O to x.4, the 
number is rounded downward. 

For a negative value, if Aexpr is between -x,5 to -x.9, the number is rounded 
downward. If the value is between -x.O to -x.4, the value is rounded upward. 

If the number to be rounded is assigned to an integer result, the value will be 
returned unchanged. 
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Example: 

Kappas = 1.8 

Deltas = ROUND (Kappa&) (Deltas will « 2) 

Kappa & = 1.4 

Deltas -= ROUND (Kappas) {Deltas will = 1} 

SGN (Aexpr) 

SGN retxims the sign of the argmnent, A negative argument returns a negative one. 
If the argument equals zero, SGN returns a zero. A positive argument returns a one. 

Example: 

Result = SGN (0) {Equals zero} 

Result = SGN (-123) {Equals negative one} 

Result * SGN (123) {Equals positive one} 

SQR (Aexpr) 

SQR returns the square root of the argument. The argument must be a positive, real 
or LQteger expression, otherwise a run time error wiU occur. 

If the value retiomed by SQR is multiplied by itself, the result may be less than the 
initial value. The loss of precision occurs because of truncation. 

Example: 

FOR Count% = 1 TO 10 

Product% = Count% * Count% 

PRINT Count%, Product%, SQR (Count%) 

NEXT Count % 

Trigonometric Functions 

Micol Advanced BASIC has four trigonometric functions. All arguments or results 
are expressed in radians (not degrees). 

ATN (Aexpr) 

ATN jdelds the arc tangent (inverse tangent) of the parameter. The value returned 
represents an angle expressed in radians in the range ±rt / 2. 

Example: 

Tangents = TAN (Radians) 
Inv_Tan& - ATN (Tangents) 
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COS (Aexpr) 

COS returns the cosine of the argument. The cosine is the ratio of the length of the 
adjacent side to the length of the hypotenuse (in a right-angled triangle). The argviment 
is the angle as expressed in Radians. 

Example: 

Cosine& - COS (30 * Pi& / 180) 

SIN (Aexpr) 

SIN yields the sine of the argument. The sine is the ratio of the length of the 
opposite side to the length of the hypotenuse (in a right angled triangle). The argument 
is the angle as expressed in Radians. 

Example: 

Sines - SIN {60 * Pi& / 180) 
PRINT Sine& 

TAN (Aexpr) 

TAN returns the tangent of the argument, (a number between and the accuracy 
limit of the data type used). The tangent of 90 degrees is infinity. 

Example: 

Tangents =- TAN (Radians^) 

Radian/Degree Conversion Functions 

Most of you are used to working with degrees instead of radians. You may find the 
following conversion Functions useful to use within your programs. 

{Take Degree as input} 

FUNC DegreeToRadian [Degrees] 

Pi& - 3.14159265 

Radian& = Degrees * (Pi& / 180) 
ENDFUNC [ Radians ] {Return Radian as output} 

{Take Radian as input} 

FUNC RadianToDegree [Radians] 

Pis - 3.14159265 

Degrees = Radians * (180 / Pis) 
ENDFUNC [Degrees] {Return Degree as output} 
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Chapter Four 

Strings 
Overview 

A string may be thought of as text- Each word or sentence of this manual may be 
thought of as a string. All data sent to the screen or the printer are sent as strings. 

Under Micol Advanced BASIC^ strings are dynamically stored. This means that 
string lengths do not have to be declared in advance, 

This section deals with strings and string manipulation functions at your disposal 
vmder Micol Advanced BASIC. You must pay special attention to this chapter as some of 
the string fxmctions operate somewhat differently than under Applesoft, Also, there are 
several additional string functions that give the string handling abihties of Micol 
Advanced BASIC much greater power than any other language you have probably seen. 

String garbage collection, a topic not well understood by many users, is also 
discussed in this chapter. 

String Function Notes 

Here are some things to pay special attention to: 

1, No string shaping function such as LEFT$ may be used xmtil the string argument 
has been exphcitly given a value. 

2, String shaping functions assume integer arithmetic and will make the conversions 
fi*om real to integer as needed. The sole exception is STR$ which assumes a real 
value as its parameter aad will make the conversion firom integer to real as 
needed Therefore, any real number within string functions, except STR$, will 

be converted to integer before the manipulation is done. Since the type 
conversion delays the programs a bit, use integer values whenever practical 

3, Strings may grow to a maximum length of 1023 characters, ^iowever, static strings 
such as This is a string" may only have a maximum length of 251 characters. 

The ASCII Character Set 

Each character has a numeric value, and this numeric value is used in order to 
evaluate strings. 

«A" < "B^ and "B" > "A" are true. If you look at the ASCH chart (Appendix F), you 
will see that ''A" has the numeric value 65 and "+" has the numeric value 43. These 
numbers are used to evaluate string expressions. 
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String Comparisons 

Strings are compared using relational operators to determine if> for example, one 
string is the same or is different from another string. Comparisons are made using the 
ASCn numeric value of each character in both strings. 

Examples: 

^^Ronald" = ^^Ronald" 
''Ronald" <> ''RONALD" 

"Ronald'' < "Steve" 
^Walter" > ''Steve" 

By comparing one string with another, strings may be sorted in alphabetical order or 
inverse alphabetical order. See also the ASC and CHR$ conversion functions. 

String Concatenation 

Concatenation is the act of merging two or more strings into one. The concatenation 
operator is the plus sign (+). The maxunum length a string can grow under 
concatenation is 1023 characters. Any attempt to create a string greater than 1023 
characters will result in an error during program execution. 

Examples: 

String$ = "This is " + "one big " + "string'" 
Stringl$ = Stringl$ -h String2$ 

Conversion Functions 

The following functions are used to return numeric results for string arguments or 
string results for numeric arguments, 

ASC (Sexpr) 

ASC returns the ASCII value of the first character of the string argument. If the 
string is empty (has no characters in it), a value of zero wiU be returned 

The value returned is always between and 127, Most characters, however, are 
actually stored internally with a value greater than 127. To know the true value of the 
character, PEEK at location 202 (True^Value) in direct page immediately after using 
the ASC ftmction. (See Appendix F: the ASCII chart.) 

Example: 

Letter$ - ^^A" 

ASCII = ASC (Letter$) {Prints 65} 
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CHR$ (Aexpr) 

CHR$ takes the nuraeric argument and returns the character corresponding to its 
ASCII value. The argument must be between and 255 or a run time error will occur. 
Values greater than 128 will repeat the text mode character set. (See Appendix P: the 

ASCn chart,) 

Example: 

Letter$ - CHR$ (65) 

PRINT Char$ {Prints the letter A} 

LEN (Sexpr) 

LEN (Length) returns the number of characters within a string or string variable. If 
no character appears within Sexpr, LEN will return a zero. All strings have a length of 
zero ioitially. You may need to use LEN to check the length of a string when using a 
string shaping function, as a possible error condition may arise. 

Example: 

String$ = "Micol Systems Inc." 

PRINT '"Number of string characters is:"; LEN (String$) 

LEN returns a value of 18, 

STR$ (Aexpr) 

STR$ converts the numeric argument into its string equivalent. 

Example: 

Stringl$ = STR$ (12,34) 



NOTE 



The string "12.34" and the real number 12.34 will appear 
the same when they are displayed; however, inside the 
computer's memory, they are stored quite differently. 



VAL (Sexpr) 

The VAL function converts the contents of the string argument into its numeric 
equivalent VAL removes any leading spaces from the striag argument before doing the 
evaluation. 

If VAL evaluates an argument with non -numeric characters, VAL will convert and 
return all the digits appearing before the non-n\imeric character or space. If the first 
character in the argument is non-numeric, VAL yields a zero. 
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Example: 

String$ = ^^12.34" 
Reals = VAL (String$) 

String Searches 

The following function is very ufieful and has no equivalent in Applesoft* Its purpose 
is in searching for sub-strings within a string, but this has very many applications 
seemingly unrelated to string searches. Examples throughout this manual will 
demonstrate some of these uses. 

INDEX (SubString$, String$, [Aexpr]) 

INDEX will return the position number of the first character where SubString$ 
occurs in String$ from one to the length of String$. If SubString$ does not appear 
within StriQg$, a zero will be returned. 

An optional occurrence value ranging from 1 to 255 may also be specified. The match 
will not be made unless the stated instance of SubString$ exists. 

Example 1: 

String$ = ""This is a string" 
PRINT INDEX {" is "*, String$) 

The PRINT statement will display 5. The first space character is the fifth character 
of the string. 

Example 2: 

Alpha$ = "abcdebxyz" 

Beta? = "b" 

PRINT INDEX (Beta$, Alpha$, 1) 

PRINT INDEX (Beta$, Alpha$, 2) 

The first PRINT will show that the first occurrence of "b" is at the 2nd position and 
the second occurrence will show the second "V* at the 6th position in the string. 

Example 3: 

Allowed? = ''AEIOUaeiou" 
REPEAT 

GET Char$ 
UNTIL INDEX (Char$, Allowed?) > 
PRINT Char$ 

This code will allow only a vowel to be entered 
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String Manipulation 

The following ftinctions will allow you to manipiilate strings in any manner reqxiired 
by your program* This string shaping ability is one advantage BASIC has over almost 
any other language and Micol Advanced BASIC has more than most B ASICs. 

INSERT$ (Stringl$, String2$, Pos_Nuinber) 

Tb write over a portion of a string using the contents of another string, use 
INSERT$. Both string arguments must be string variables. The contents of Stringl$ 
will be used to write over the characters of String2$ starting at the specified position. 
Each character will be copied over String2$ until all characters are copied or the end of 
either string is reached 

Example: 

Stringl$ = ^Italy" 

String2$ ="The rain in Spain falls mainly on the plain." 

INSERT$ {Stringl$, String2$, 13) 

PRINT String$ 

This code wiU print "The rain in Italy falls mainly on the plain.^ 

LEFT$ (Svar, Aexpr) 

LEFT$ yields the nximber of characters specified by Aexpr starting firom the left side 
of Svar. If the number of characters requested is greater than the string length, a run 
time error will occur. If in doubt, check the string length with the LEN function before 
executing this function. 

Example: 

String$ = '^Micol Systems Inc." 
PRINT LEFT$ (String$, 5) 

The word "Micol" wiU be printed, 

LOWER$ (Svar) 

LOWER$ changes all the uppercase characters of a string into lowercase characters. 
All other letters in the string variable are left unaltered, A string variable is the only 
argument accepted. 

Example: 

String$ ^ '^ABCDEFGHIJ" 

Low$ = LOWER$ {String$) 

PRINT Low$ {Will print abode fghij} 
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MID$ (Svar, Aexprl [^expr2]) 

]VIED$ returns a substring of Svar starting at Aexprl, If Aexpr2 is not present, the 
entire string is returned firom Aexprl to the end of Svar, otherwise MID$ returns the 
number of characters specified If the starting character position is beyond the last 
character of Svar, a run time error will ocoirc. 

Example: 

String$ - '^Micol Systems Inc." 

PRINT MID$ (Strings, 7, 7) 
The word "Systems" will be printed 

RIGHT$ (Svar, Aexpr) 

RIGHT$ returns the characters specified by Aexpr starting fit)m the right side of 
Sexpr. If the number of characters requested is greater than the length of Svar, a run 
time error wiU occur. If in doubt, check the string length with the LEN fimction before 
executing this function* 

Example: 

String$ - '^Micol Systems Inc-" 

PRINT RIGHT$ (String?, 12) 

The words "Systems Inc," will be printed, 

UPPER$ (Svar) 

UPPER$ will change all lowercase characters of a string into uppercase characters. 
All other characters in Svar are left unaltered. A string variable is the only parameter 
accepted. 

Example: 

Strings - ""abcdef ghij" 
Up$ - UPPERS ( Strings ) 

PRINT UpS {Will print ABCDEFGHIJ} 



WARNING 



Avoid writing string manipulation functions on both sides 
of a comparison operator, where both sides return a string 
result. A problem arises because a single string 
manipulation buffer is maintained for all string 
manipulation functions which allows only one function to 
be performed at a time. This greatly increases the speed 
of the operations as string transfers are minimized. 
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System String Functions 

These functions let you use some system functions by converting the information into 
a character string. You may manipulate these string data as any other string. 

DATE$ 

DATE$ returns the date in the format stipulated by the Control Panel settings- 
Example: 

Day$ = DATE$ 

PRINT Day$ 

Something like 25/Peb/92 will be displayed, 
PREFIX$ 

PREFIX$ returns a string with the name of the current default prefix. 

Example: 

Voiuine_naxne$ = PREFIX$ 
PRINT Volume_Name$ 

TIME$ 

TIME$ returns the time from the ApplelIGS clock in the format set by the control 
panel, for example HH:MM:SS. 

Example: 

Clocks = TIME$ 
PRINT Clock? 

The time is displayed like this: 10:24:23 

String Garbage Collection 

Garbage is memory which was once used for a purpose, but is now unused and lost to 
the system. 

When a string is reassigned another value, the new string must be built in another 
area of memory. The pointer (or address) to the old string is changed to point to the new 
string, and the area in memory to which the string variable originally pointed becomes 
lost, or garbage. Eventual! y> most of the string memory will become garbage and need to 

be reclaimed. This reclaiming is done using a process called "String Garbage Collection". 
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FRE(O) 

FKE (for Free) forces a collection of all xinused character strmgs and returns the 
number of bytes available to the system for building further character strings. 

The ai^ument may be any legal mathematical expression, but a value of zero is used 
by convention. The parameter has no effect on the result, but is required by the 
Compiler, otherwise an error wiU occur. 

If you assign FRE (0) to a real variable, the entire number of bytes remaining wiU be 
returned* If you assign FRE (0) to an integer variable, Uie number of banks available to 
the program will be stored in Direct Page location True_Value (202) and the rest of the 
address will be returned in the assigned variable (in two's complement notation). If you 
are using the integer FRE (0), then retrieve the bank number immediately after 
executing FRE (0) as location 202 is also used for other purposes. 

If FRE (0) retiims an unacceptably small number of bytes, use the BANK_NO 
compiler option, described in Part Three, Chapter One, to allocate more memory for 
string storage, if possible. By default, a program is allocated one bank (64K) for string 

storage. 

Example: 

Free_BYtes% • FRE (0) 

Free_Banks% ^ PEEK (202) 

Total__Bytes& =- Free_Bytes% + 65536 * Free_Banks% 



or 



Total_Bytes& = FRE (0) {Same result} 



Micol Advanced BASIC uses an efl&cient, double-linked garbage collection algorithm 
that seldom produces, if ever, any noticable delay 



Programmers 



Tbolbox Note: Do not confuse the results of FRE (0) with 
the functions of the Tool Memory Manager which returns 
the amount of free memory in the computer. 
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Chapter Five 

Making Decisions 

Overview 

We all have to make a large number of decisions in our daily lives. The vast majority 
of programs also have to make decisions, and actions have to be taken based on these 
decisions. 

We have discussed relational operations earlier in this manual. In this chapter yt)u 

will learn to use these relational operations and have your program.s take action based 

on the results of these relational operations- 
Decision making is probably the most important aspect of computer programming. It 

is important you have a complete understanding of this topic if your programs are to 

function as intended. 

Program Indentation 

It is important that your program source code reflect the logic within your programs. 
The logic within your programs can best be represented by line indentation. Once a 
statement falls under a particular control structure, this statement should be indented 
one Tab. Once this control structure is resolved, the Tab should be removed. There 
should be one Tab for each active control structure. 

If you are confused, simply look to the examples within this manual. Each example 
reflects the standard indentation. 

Single Choice Decisions 

As we have stated earlier in this manual, a relational operation yields a result of 
T_.JE or FALSE, Based on this result, we may wish to have a certain set of actions 
taken. In addition, we may also wish that an alternate set of actions will be taken in the 
event the first set of actions is not taken. That is, we have a choice to make, one set of 
actions or another. It is in this circumstance that we will wish to make use of the most 
important statement in computer programming, the IF statement. 

The IF Statement 

Simple IF 

IF Relop THEN Statement [{: Statement 11 \ 
[ELSE Statement [{: Statement}]] 
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Relop is evaluated and produces a boolean result (TRUE or FALSE), If the result is 
TRUE, the statementCs) following the keyword THEN until the end of the line or 
optional ELSE keyword are executed. If the ELSE statement is present and Relop is 
FALSE, the statements following the ELSE until the end of the hne will be executed In 
both cases, when the instructions have been executed, the flow of execution continues on 
the next hne of instructions. 

The IF,,THEN,.ELSE statement is designed to provide an ELSE option to the 
Applesoft IF..THEN structiure. This statement works correctly when the statements to 
be executed after the THEN or the ELSE are on a single Hne of code. More than one 
statement may be written after the THEN or the ELSE by preceding the second and 
following statements by a colon (:), 

Example: 

Op$ = "-" 

IF Op$ = '*+" THEN Num = 2 ELSE Num ^ 3 

Block IF..THEN,.ELSE 

IF Relop THEN BEGIN 

Statement 

[{: Statement}] 
[ELSE BEGIN 

Statement 

[ {: Statement 1 ] 1 
ENDIF 

Relop is evaluated and produces a boolean result (TRUE or FALSE), If the result is 
TRUE, the statements following the keywords THEN BEGIN until the ELSE (if 
present) or ENDIF are executed. If an ELSE BEGIN block is present and Relop is 
FALSE, the statements following the ELSE BEGIN imtil the ENDIF will be executed. 
In either case, when the instructions have been executed, the flow of execution continues 
after the ENDIF, 

To allow more than one line of code for either the IF or ELSE statement, add the 
BEGIN keyword The BEGIN keyword encloses other Micol Advanced BASIC 
statements within the IF„THEN„ELSE„ENDIF block structure. 

ENDIF is used to close an IF BEGIN or ELSE BEGIN (if present). ELSE or ELSE 
BEGIN also close an IF BEGIN. If no BEGIN is present, the end of line will terminate 
the conditional statement. If confused, just study the examples that foUow. 

Example: 

IF 1 = 2 THEN BEGIN 

PRINT *^This line will never be executed'' 

PRINT "Neither will this line" 
ELSE BEGIN 

PRINT ^This line will be executed" 
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PRINT '"And so will this one" 
END IF 
END 

The IF-THEN also accepts a boolean variable as part of the expression. 

Example: 

Flag! = TRUE 

IF Flag! THEN Nixm_Of_Truck% = 10 
or 

IF Flag! - TRUE THEN Num_Of_Truck% » 10 

It is preferable, however, to use the first method because if the boolean has been set 
to an uncertain value, the expression may never evaluate to TRUE, 

An IF block may contain one or more IF blocks within it. There may be as many as 
20 IF blocks nested within another. 

Example: 

IF Outer_Flag! THEN BEGIN 

IF Middle_Flag! THEN BEGIN 
IF Inner^Flag! THEN BEGIN 

PRINT '^All conditions met" 
ELSE BEGIN 

PRINT ""Inner^Flag! not true" 
ENDIF 
ELSE BEGIN 

PRINT ''Middle_Flag! not true" 
END IF 
ELSE BEGIN 

PRINT '^Outer_Flag! not true'' 
ENDIF 

Consider using the multi-choice construct CASE_OF if more than ovto 
IF..THEN„ELSE structures are nested. 

Multi-Choice Decisions 

Multi-choice decisions occur whenever there are several possible actions that may be 
taken based on a particular situation. Suppose, for example, an office manager has to 
base the bonus situation of the salespeople in his office on the number of products sold 
by each salesperson in a month. If there are severed categories of bonuses, deter mini ng 
the correct bonus can get very difficult using IF statements. One solution is a 
CASE_OF statement that functions in many ways as an IF statement, but allows for 
many possible choices. 
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The CASE_OF Statement 

CASE_OFAexpr 
DO Labell, Label2 

Stateineiit(s) 
ENDDO 
[{DO Labels, Label4 

Statement(s) 
ENDDO}] 
[ELSE_DO 

Stateinent(s) ] 
ENDCASE 

CASE_OF allows the user to choose one option among many without having to make 
lose of multiple single conditional statements. 

The CASE_OF statement evaluates Aexpr and selects one DO.. ENDDO block from 
the other DO»ENDDO blocks using the result of the evaluation. If Aexpr yields a real 
result, only the whole number portion is used. 

A CASE_OF statement must have at least one DO.,ENDDO block of statements, 
and may have as many DO„ENDDO blocks of statements as is necessary. 

The DO..ENDDO structure is made of a list of CASE labels followed with a block of 
statements to be executed on the lines of code below. When a label within a 
DO.JENDDO block matches the result of the arithmetic expression, the statement(s) in 
the DO,.. ENDDO block of statements will be executed. 

The DO list may have from one to twenty labels separated by commas. The label is 
always an integer constant ranging from ±32767. A label may be preceded by a lesser 
than (<) or greater than (>) symbol to make a range of labels. No label shotdd be 
repeated as only the first match is used- 

If a match is noi made and an ELSE_DO appears after the last DO. .ENDDO block, 
the statement(s) following the ELSE_DO until the ENDCASE will be executed. The 
ELSE_DO must be the only statement on the Une of code. "* ae control of flow will 
continue at the line of code after the ENDCASE. It is always a good practice to have an 
ELSE_DO block to handle the unexpected conditions. 

Example: 

Number* - -100 
REPEAT 

CASE_OF Number% 

DO 1, 2, 3, 4, 5, 6, 7, 8, 9. 10, > 80 

PRINT Nurnber%;" is positive'' 
ENDDO 

DO -1, -2, -3, -4, -5, -6, -7, -8, -9, < - 79 
PRINT Nun±ier%;" is negative "; 
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PRINT ^isn't it?'' 
ENDDO 
ELSE_DO 

PRINT Nuinber%;" is not in range" 
ENDCASE 

Number = Niimbex + 1 
UNTIL Nujnber% > 100 

If a matcli is not made and an ELSE_DO does not appear after the last 
DO..ENDDO block, control of flow continues at the line of code after the ENDCASE 
statement. 



NOTE 



A static string may also be used as a label within a DO 
line. Only the first character of the string will be used, 
and is the same as if the label had been entered as the 
ASCn valiie of the first character instead. 



Example: 

String$ = ^^Aardvark'^ 
Ascii% = ASC (String$) 
CASE_OF Ascii% 

DO ""A", "a" 

PRINT "^Letter was upper or lower case A" 

ENDDO 
ENDCASE 

CASE^OF statements may be nested within other CASE_OF statements. The 
maximum level of nesting allowed is 8 levels deep. The nested CASE statement is 
placed in a DO..ENDDO structure. 
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Chapter Six 

Basic Input/Output of Information 

Overview 

Virtually all programs accept information from some source, process this 
information, and send this processed information to a storage or display device* 

Principal sources for input are through the computer keyboard and a storage device 
such as a disk drive. Less often, the input of information is from the program itself The 
output from the program is usually sent to a display device such as a monitor or the 
printer or to a long term storage device such as a disk drive. 

Data Input 

Input is anything that can be entered into the computer using an input device, 
usually the keyboard, or read from a storage device such as a disk drive. 

Internal Data Entry 

DATAVar[{,Var}] 

DATA statements are used to place specific values into memory that may later be 
retrieved during execution of the program. 

DATA statements are placed at the beginning of the program after the optional 
compiler directives. The DATA statement must be placed in the correct position in the 
program in order to be compOed Please see the Program Order section in Chapter One 
of Part Three, 

Only int-^ger, real and string literals are accepted as datum for a DATA statement. 
Each datum is separated from the next by a comma. The length of a DATA statement is 
limited only by the length of the program line. The number of DATA statements is 
limited only by the memory available. 

Real literals must be distinguished from integer literals by having the terminating 
fraction written in decimal form (i.e 13,0). Integer hterals greater than 65535 will be 
considered real. String literals must be enclosed between double quotes. Booleans may 
not be used lq a DATA statement 

Example: 

PROGRAM Data_Example 

DATA 1, 1.0, 1.0E25, ^One" 

DATA statements may not be empty (have a non- definite value) as in an Applesoft 
BASIC program or be followed by any other statements on the same line. A DATA line 
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must have a literal between each comma otherwise the Compiler wiQ signal an error. 

Example: 

{Missing values are illegal and will 
cause errors during compilation} 
DATA ^TEXT" , , "MORE TEXT " , , , , , 

READVar[[,Var}] 

The function of the DATA statement is to give a method to store constant 
information that may be used each time the program is executed. These data are 
accessed within a program by means of a READ statement, A DATA statement only has 
meaning when used in conjimction with a READ statement, 

lb READ data, a loop of some kind is usually used The DATA values are read one 
by one, starting from the first line of DATA- The DATA pointer cannot turn back or skip 
any values, but may be moved back to the beginning using the RESTORE command 

If the program tries to read more values than are available, an error will occur. 

Leaving values unread does not produce an error. 

If the data types in the DATA and READ statements do not match, an error will 
occur when the program tries to read in the datum. 

Example 1: 

PROGRAM Read__Data 
DATA 1, 1.0, ""One" 
{Main Program} 

READ Integer% {Read integer datum} 
READ Real& {Read real datum} 
READ String$ {Read string datiun} 
END 

Example 2: 

PROGRAM Read_Numbers 

DATA 1, 2, 3, 4 

DATA 5-0, 6.0, 7.0, 8.0 

DIM Number% (3), Number (3) 

{Main Program} 

FOR Counter% « TO 3 {Read first DATA line} 

READ Number % (Counter%) 

PRINT Number% (Counter%) 
NEXT Counter% 
FOR Counter - TO 3 {Read second DATA line } 

READ Number (Counter) 
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PRINT Number (Counter) 
NEXT Counter 
END 

RESTORE 

RESTORE places the DATA pointer back to ita starting position. This means the 
values in the DATA statements may be reread. 

Example: 

PROGRAM Read_Numbers 
DATA 1, 2, 3, 4 
DATA 5, 6, 7, 8 
■ DIM Nmnber% (7) 
{Main Program} 
HOME 

{Read values in DATA statements} 
FOR Counter% * TO 7 

READ Number% (Counter%) 

PRINT Number% (Counter%) 
NEXT Count ex% 

RESTORE {Bring DATA pointer to position one} 
{Reread values in DATA statements} 
FOR Counter% = TO 7 

READ Number % (Counter%) 

PRINT Number% (Counter%} 
NEXT Counter% 
END 

Keyboard Entry 

GETSvar 

GET is used to read one character from the keyboard and place it into a string 
variable. The character entered is not echoed on the screen. 

The program continues execution with the next statement without waiting for a 
press of the Return key. The cursor is displayed until a character is entered 

GET accepts only a string variable as its argument. The Compiler will issue an error 
if a numeric variable is used. Use the VAL function to convert the digit if reqiiired. 
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NOTE 



<Control>C will not interrupt the execution of GET. All 
Control characters may be read firom the keyboard with 
GET, 



See also the next chapter for another use of GET. 

Example: 

REPEAT 

GET Vowel $ 

IF INDEX (Vowel$, "AEIOUaeiou") > THEN PRINT Vowel$ 
UNTIL INDEX (Vowel$, ^AEIOUaeiou") > 

INKEYSvar 

INKEY scans the keyboard to determine if a key has been pressed, IN KEY is 
similar to GET except INKEY does not wait for a key press and does not display a 

cursor. 

If no key has been pressed, an empty string is returned in Svar. If a key has been 
pressed, a one byte string representing the key pressed is created in Svar, 



NOTE I 

I To be effective, INKEY must be used within a loop. 



Example: 

REPEAT 

INKEY Character$ 

IF Characters <> ^" THEN PRINT Character$ 
UNTIL Characters <> "" 

INPUT ['^Prompt string";] Var [{, Var )] 

INPUT accepts data from the current input device (usually the keyboard). An 
optional message, enclosed in quotation marks, may be displayed prompting the user for 
the necessary input- 

The prompt must appear after the keyword INPUT, and be followed by a semi-colon 

(;), and the list of variables. If no prompt is specified, INPUT automatically displays a 
question mark (?) as the prompt. 
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NOTE 



No question mark is displayed when the prompt string 
present hut empty; use this to hinder any prompt. 



IS 



INPUT may have any number of variables, each separated by a comma. 

INPUT accepts simple variables and arrays of type integer, real and string. Boolean 
variables are not accepted* 

The INPUT statement will ask for the second, and any subsequent input on a 
separate Hne by displaying a question mark (?) for each missing input 



WARNING 



Pressing the Return key for each piece of information is 
the only way to accept data from an INPUT with 
multiple variables* The comma (,) and semi-colon (;) are 
not accepted as delimiters as under Applesoft BASIC. 



In order to make programs easier to understand, use one INPUT statement for each 
piece of information. 

INPUT accepts <Control>S to insert a space. An input may be terminated by 
pressing <Control>C only if the NOT_C compiler option is not used. The Delete key 
erases a character dining response to an input (the delete mode may be altered during 
execution, see Appendix A). 



NOTE 



Memory locations 4 and 5 in the Library^s Direct Page 
control the maximum number of characters that may be 
entered using INPUT; 255 is the default. This value is 
stored as a hexadecimal number in least significant byte, 
most significant byte order. Do not POKE a value 
greater than a 3 into location 5 or an error will occur 
when the next INPUT xs encountered. 



The bell wiU ring if the maximum niunber of characters allowed in an INPUT Hne 
has almost been reached. 

String Input Rules 

Characters with ASCII codes from 32 to 127 may be entered from the keyboard. 
Control characters will be ignored. 
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Numeric Input Rules 

If, during a numeric input, the user enters something other than a numeric value, 
the message ''?Reenter" will be displayed. A question mark prompt will appear on the 
next line and the computer will wait for the appropriate input. For a real input, all 
non-n\nneric characters except a capital "E", a period (.), a comma (,), a plus sign (+), and 
a minus sign (-) will be rejected For integer input, only digits, a comma (,) and the plus 
and minus signs are allowed input. The commas are for user convenience and are 
ignored 

A numeric expression, such as ""S * 4 / 6", is not accepted as numeric input 

Examples: 

INPUT "Enter name: "; Najne$ 

INPUT "Enter age: ''; Age% 

INPUT '^Enter any real value: "; Numbers 

See also the next chapter for other uses of INPUT. 

Entry from Other Devices 

INSLOT (Slot^Number) 

INSLOT is used to get characters from the device connected to the slot or port 
number specified. The argument may be any integer literal between and 7; a is used 
to return input to the keyboard Any negative value or a value greater than 7 wiU retimi 
an error. 



IMPORTANT 



D^SLOT is best used in conjunction with a GET. 
INPUT may be used after an INSLOT, but because 
rNPUT expects a carriage return to terminate an entry, 
INPUT is only suitable in limited situations. 



Example: 

INSLOT (2) {Input from slot 2} 

GET Char$ {Reads character from port 2} 

INSLOT (0) {New input from keyboard} 

Data Output 



Output is information that can be sent from the computer, usually to a screen display 
or printer, or to a disk device for long term storage. 
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Screen Display Control 

The foilowing commands control the manner in which text is output to the screen. 

DELAY == Aexpr 

DELAY pauses the program the stipulated time. One increment equals about 0.01 
seconds for a normal Apple IIGS. If you have an accelerator card installed, the delay will 
be that much quicker. 

Example: 

DELAY = 100 {Pause about one second} 

HOME 

HOME erases the contents of the text window and places the cursor at the top left 
comer of the screen. 

Example: 

FOR Line% = 1 TO 23 

PRINT "This fills part of the screen" 
NEXT Line% 
HOME 
PRINT '^Now the screen is almost clear" 



NOTE 



To move the cursor to the top left comer of the screen 
without erasing the screen, use VTAB (1): HTAB (1). 



INVERSE 

INVERSE causes the subequent characters) sent to the screen to be displayed in 
inverse video (reversiDg the black and white of a character block). 

INVERSE will stay in effect until a NORMAL command is encoimtered. 

Example: 

INVERSE 

PRINT ''This is an inverse display" 

NORMAL 

PRINT "This is a normal display" 
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MS^TEXT 

MS_TEXT (for Mouselfext) allows the ability to send MouseText characters to the 

screen. 

MouseText characters are a set of graphical characters designed specifically for the 
Apple II computer, Thia character set has the ASCII range 64 ($40) through 95 ($5F), 

Example: 

{Display keycap symbols } 
MS_TEXT {Turn on MouseText} 
PRINT "Q H U J K M" 
MS_TEXT {Turn off MouseText} 



IMPORTANT 



A second MS_TEIXT txims o£F the effect of the previous 
MS TEXT. 



NORMAL 

NORMAL restores the display to the standard text characters. NORMAL turns ofif 
the previous INVERSE. NORMAL character display is the default mode. 

See the example for INVERSE. 

SPEED = Aexpr 

SPEED controls the rate at which the characters appear on the screen. Aexpr must 
he between 1 and 255; the minimum speed being 1 and the maximum speed being 255. 
The default display rate is set to 255, the maximum speed. A speed of zero is equal to a 
speed of 255. 

Example: 

SPEED - 100 

PRINT ^This line will print slowly^ 

SPEED = 255 

PRINT '^Now printing at normal speed'' 

Unformatted Text Output 

Pnmr [Expr] [;;| [J [Expr] 

PRINT is used to display all data types including boolean. 

Any legal matii or string expression, literal or variable may appear inside a PRINT 
statement. Each expression will be evaluated when it is executed- If a logical expression 
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is in a PRINT statement, the result of the comparison (TRUE or FALSE) is printed 

When a semi-colon (;) is placed at the end of a statement, the semi-colon prevents a 
Carriage Return (ASCII #13), needed to move the cursor to the next line. Any 
subsequent output following the semi-colon is printed on the same Hne, The cursor 
remains to the right of the last character printed The next item to be printed will 
appear at the current cursor position. 

A comma (,) at the end of a statement places the cursor at the next tab column (1, 16, 
32, 40, 48, 56, 64, 72 or 80). The contents of the next PRINT is displayed starting at 
that position- 

Aajrthing other than a semi-colon (;) and a comma (,) as the last character ui a 
PRINT statement will generate a carriage return (ASCII #13) as the last character 
output and place the cursor at colxnnn 1 of the next line. If the cursor is already on a 
new line, an empty blank line will be displayed or printed. The screen will scroll if 
necessary, 

TAB and SPC may also be used within a PRINT to format the display. 



NOTE 



A question mark (?) may not be used as a shorthand 
notation for PRINT as under Applesoft BASIC. 



Examples: 

PRINT ^Your name is "; Naine$;" your age is ''; Age% 

PRINT {Only sends a <CR>} 

PRINT 'U + 2 + 3 - "; 1+2+3 

PRINT 1, 2, 3, 4, 5 

PRINT 1.5 > 9.3 {Will print FALSE} 

See also the next chapter for other uses of PRINT, 

See also Part Six, Chapter One for debugging uses of PRINT. 

Formatted Text Output 

PRINT USING Mask$; [Expr] [;] [J [Expr] 

PRINT USING is used to display real values to the current output device using a 
particular format. Formatting is made to both sides of the period of the real value. 

Except for the real value formatting ability, PRINT USING functions just Hke 
PRINT, TAB or SPC statements may be used within PRINT USING if needed. 

A mask is used to define the format of the output. The mask may be a string literal 
or string variable. Rules for the mask are as foUows: 

1, Only dollar signs ($), number signs (#), commas (,) and a single period (,) are 
allowed within a mask- 
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5. 
6. 



Commas may appear only to the left of the period. If digits are to be output, 
commas will appear in the printed output in the same position they appear in 
the mask. 

Number signs may appear on either side of the period. Every occurrence of the 
number sign will be replaced with digits or padded with spaces on the left of the 
period and by digits or padded with zeros (0) on the right of the period- 
Dollar signs are allowed only on the left side of the period Each occurrence of a 
dollar sign will be replaced with a space until just before a digit would appear, 
then a single dollar sign will be printed. Additional dollar signs will be replaced 
by the appropriate digits^ 

A fraction m^I be truncated, not rounded. 

If the number should require more places on either side of the period than are 
specified in the mask, the digits will not be displayed. Make sure to allow 
enough room in the mask for all possible values. 



NOTE 



The character value of the comma and period may be 
changed to conform to the non-English speaking world 
The comma and period may be changed to other 
characters by modifying the appropriate memory 
locations Hated in Appendix A. 



To print monetary values, use a mask similar to this: Mask$ = "$,$$$, $$$.##^. 
lb print nimieric values, use a mask similar to this: Mask$ = '*#,###,###.##'' 

Example: 

Numbers = 1234.567 

PRINT USING "$$$,$$$,$$$.##"; ^^The value is"; Numbers 

The line above will print: The value is $1,234.56 (with five leading spaces). 

Example: 

Mask$ = «###^###^ ###.#" 

Numbers = 123456.78 

PRINT USING Mask$;"The value is "^ ; N\imber& 

The line will indicate The value is 123,456.7 (with four leading spaces). 



NOTE 



Ho format the output of an integer value, then simply 
assign this integer value to a dummy real variable, and 
use the dummy real variable in the PRINT USING 
statement. 
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Cursor Positioning 

The following commands affect the movement of the screen cursor, and sometimes 
the printer head. Cursor positioning is affected by the borders of the screen which may 
be altered during execution of the program making it possible to create text windows. 
Please see Appendix B for specific information. 

POS (Aexpr) 

POS (for Position) returns the current horizontal position of the cursor at the 
moment POS is executed. The value returned is jErom one to 80. One is the left-most 

side and 80 is the right-most side of the screen. 

The argument is ignored, and has no effect on the result of the evaluation of POS, 
but mvist be present, otherwise an error will occiir during compilation. 

Example: 
HOME 

PRINT ^"Position: ";POS (0) 

This statement returns the number 11 for the position of the cursor, 

SPC (Aexpr) 

SPC (for space) prints the specified number of spaces to the current output device 
and may only be used inside a PRINT statement, 

Aexpr may be any valid arithmetic expression, SPC must be in the range one to 255 
otherwise an error occurs at ran time. If Aexpr is real, its value will be truncated, 

SPC moves the cursor or print head the number of spaces specified starting fi^om the 
current cursor position. If the cursor is moved past the right margin, it continues 
spadng on the line below. 



IMPORTANT 



Semi-c :>ns must be used after each SPC, otherwise a 
carriage return will be generated destroying the effect of 
SPC. 



Example 1: 

PRINT SPC (15); "The total is:";TotalS 

TAB (Aexpr) 



TAB (for Tabulation) is used to position the cursor to the specified position on either 
the screen or printer and may only be used inside a PRINT statement. The position 
values range from 1 to 80, The first horizontal position (1) being on the left margin and 
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the last one (80) on the right margin. 

Aexpr may range from one to 255. Values from 81 to 255 will tab on lower lines of 
the screen. 

If Aexpr is real, only the whole number portion will be used, 

If a PRTON statement is in effect, TAB wiU move the print head at the position 
specified, in a forward direction only. 



IMPORTANT 



Semi-colons must be used after each TAB statement, 
otherwise a carriage return will be generated, destroying 
the effect of the TAB, 



Example 1: 

PRINT TAB (15};Total$ 

HTAB (Aexpr) 

HTAB (for horizontal tab) moves the cursor to the horizontal position specified by 
Aexpr. The cursor may be moved from left to right or right to left. 

Aexpr may range from one to 80. Any values outside this range will result in a run 
time error. If Aexpr is real, only the whole number portion will be used. 

Example: 

PROGRAM Demo_HTAB 

HOME 

HTAB (36) 

PRINT ''is the''; 

DELAY - 50 

HTAB (31) 

P INT "This'S^ 

DELAY =50 

HTAB (43) 

PRINT ''proper order." 

END 

VTAB (Aexpr) 

VTAB (for Vertical tab) moves the cursor vertically to a specific line on the screen. 

The argument may be any valid arithmetic expression with a result ranging from one 
to 24, Any values outside this range will result in an error at run time. If Aexpr is real, 
only the whole number portion will be used. 
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The cursor may move in either vertical direction. 

Example: 

PROGRAM D€ino_VTAB 

HOME 

VTAB (4) 

PRINT '^On line four" 

END 

Output to Other Devices 

OUTSLOT (Slot^Number) 

OUTSLOT is iLised to send subsequent output through a device connected to the 
specified slot number The argument must be a digit between and 7; any negative 
value or value greater than seven will cause an error, 



IMPORTANT 



NOTE 



A 3 is used to return output to the screen. 



None of the screen formation statements such as TAB 
will work when used in conjunction with OUTSLOT. 



Example: 

OUTSLOT (2) {Output through slot 2} 

PRINT String$ {Sends character (s) to port 2} 

OUTSLOO'O) {Sends output to the screen} 

PRTON 



PRTON (Printer On) turns on the communication link to the printer and redirects 
all output to it PRTON assumes the printer is connected to slot one (printer port) of 
the computer. If this is not the case, use OUTSLOT. 

PRTON does not interrupt the execution of the program if the computer is connected 
to a serial printer even if the printer is turned off. However, the program may hang if a 
parallel printer is turned oflf. 



Example: 

PRTON 

PRINT ""This line is written on the printer' 
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TEXT 

PRINT "This line is written on the screen" 

TEXT 

TEXT turns off the conimunlcation link to the printer aad restores the screen as the 
current output device. 

Example: 

PRTON 

PRINT "This line is sent to the printer," 

TEXT 

PRINT ''This line is sent to the screen," 



NOTE 



TEXT may only be used to turn the printer off and the 
screen display back on if the printer was origiiially turned 
on with a PRTON. 
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Chapter Seven 

Disk Filing 
Overview 

It is often the case that data generated by a program must be stored in some long 
term device for later usage. Also, data stored from some outside source often must be 
read in from a long term storage device for immediate usage. Such data are usually 
stored as disk files. 

A typical example of such file usage is in a word processor. Once the text is 
generated within the word processor, it must be saved, or all the work would be wasted 
once the computer is turned off. Conversely, this text may have to be read back into the 
word processor at a later time for further modifications. 

Disk filing commands are necessary to maintain and access these files. Access and 
maintenance of disk files is the topic of this chapter. 

File Management 

These commands allow you to manage the disk files on your system. 

CAT$ 

CAr$ is designed to get file information £rom a directory. Each use of CAT$ returns 
a string containing a file directory entry from the default directory, just as it is displayed 
using the CATALOG command imder the Shell (minus the heading). 

The volume information is returned on the last line, concatenated with the last file 
name and information, separated by a carriage return (ASCII 13). 

CAT$ must be contained in a loop» If more directory i ^formation can be read, 
True_Value (memory location 202) will contain a zero. If the last line has been read, 
True_Value will be non-zero. Remember that True_Value is used for other purposes 
and should be tested immediately after each use of CAT$. 

Example: 

PROGRAM Show_Directory 

{Display directory header} 

HOME 

PRINT ''Filename'^■ TAB(21); ^Type"; TAB(27); \ 
"Blocks"; TAB(36); ^'Created"; TAB(43); \ 
"Time"; TAB(55); ''Modified"; TAB (64) ; "Time"; \ 
TAB (74) ;"EOF" 
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PRINT 

{Get directory listing} 

REPEAT 

String$ = CAT$ 

IF PEEK (202) <> THEN BEGIN 
PRINT String$ 

END IF 
UNTIL PEEK (202) <> 
END 



IMPORTANT 



The entire directory file must be read at one time, 
otherwise the directory file will remain open 
unnecessarily, which wiU probably cause problems at a 
later time. You may have to read the directory entries 

into a string array. 



NOTE 



If you wish the contents of a directory other than the 
default directory, you will have to change the default 
prefix with the PREFIX command. You may first have to 
save the current directory with use of the PREFIX$ 
command, then reinstate the original directory after the 
directory has been read. 



COPY Svarl TO Svar2 

COPY duplicates the file defined in Svarl into a file with name Svar2. Svar is the 
Pathname of the files and may be either a paring variable or a string literal. 

If Svar2 is assigned an empty string, the file specified in Svarl will only be read If 
an error occin^ during the read, True_VaIue (location 202) will contain a non-zero 
value. This allows you to verify a file without generating an error. 

Example: 

Filel$ = 'VRAM5/File'' 

File2$ = *^/RAM6/New.File" 

COPY Filel?, ^" {First Verify Filel$} 

IF PEEK (202) ^ THEN COPY Filel$ TO File2$ 
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CREATE Svar 

CREATE will generate a directory file (type DIR). Svar is the Pathname of the new 
directory and may be either a string variable or a string literal* Svar must not already 
exist or an error will be generated. 

CREATE locks the newly created directory. 

Example: 

CREATE ^VMicol.Adv, BASIC /New. Dir" 

DELETE Svar 

DELETE will erase the file specified from the appropriate directory, Svar is the 
Pathname of the file to be deleted and may be either a string variable or a string literal, 

A file may not be deleted if it is open or locked. A directory file may only be deleted if 
it is empty Use this command when a specific file is no longer needed. 

Example: 

DELETE 'VRAM6/FILE" 

FLUSH 

FLUSH will empty all open file buffers to their respective files. 

The main function of FLUSH is in file security. If any program runs a significant 
time with open files and the program malfunctions, without periodic use of FLUSH, the 
information in the bu£rer(s) may be lost. This command ensures that all data inside the 
fiie bufrer(s) will be transferred to their respective disk files. 

A program using the command FLUSH will be slightly slower because of the time 
needed to copy the information to disk, but you will be certain to have all the 
information saved should a power surge or interruption occur. 

Example: 

FLUSH 

FORMAT Svar 

FORMAT is designed to initiaHze a disk device such as a floppy or a RAM disk, Svar 
is the volume name the disk will have once formatted and may be either a string 
variable or a string literal. 

The FORMAT command displays the location and the names of all devices connected 
to the computer. The user will select the appropriate device with the Up and Down 
Arrow keys and press Return to display the GS/OS Formatting Dialog Box. 

The user should set the controls of the Dialog Box to ProDOS for the operating 
system and 800K 2:1 for the interleave, if necessary then presses Return to start 
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formatting. 

Example: 

FORMAT 'VWork.Disk" {The disk will be named Work, Disk} 



WARNING 



The iiser must be certain he/she wishes to format the 
specified device as once the final Return is pressed, all 
information on the device will be erased It is 
recommended a warning message be displayed, and 
possible exit allowed, before FORMAT is executed. 



LOCK Svar 

LOCK is used to protect a file from being deleted or modified. Svar is the Pathname 
of the file to be locked and may be either a striag variable or a striDg literal. 

When a file is locked, an asterisk (*) precedes the filename when a directory is 
displayed to show that the file is protected. 

Example: 

LOCK "/RAM6/FILE" 

ONLINE$ 

ONLINE$ returns a string which contains all the current online volume names. 

Each volume name is separated by a Return character (ASCII 13). This Return 
character may be used to isolate each online volume name within your program. 

Example: 

OnLine_Naine$ = ONLINE? 
PRINT OnLine_Naine$ 

PREFIX Svar 

PREFIX uses Svar to set the defa^llt prefix- Svar is the Pathname to a directory and 
may be either a string variable or a string literal. 

If Svar contains an empty string ("")> the system will ordy display the default prefix 
to the screen. If Svar is not empty, the default prefix will be set to Svar. The volume 
must be online when this command is executed; otherwise^ an error will occur. 

Example: 

PREFIX ""/RAMe/Directory" 
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RENAME Svarl TO Svar2 

RENAME will change the name of a file, directory or volxime. Svarl and Svar2 may 
be either string variables or string literals. 

Svarl is the Pathname to the original file and Svar2 is the Pathname the file will 
have. If Svarl and Svar2 are on the same volume, but in different directories, Svarl wiU 
be moved to the directory stipulated in Svar2. 

Svarl must be unlocked, and Svar2 must not already exist. 

Example: 

RENAME 'VRAM6/File" TO 'VRAM6/Newf ile" 

UNLOCK Svar 

UNLOCK removes the protection on a file so that it may be erased, modified or 
renamed. Svar is the Pathname of the file and may be either a string variable or a 

string literal. 

A space rather than an asterisk indicating that the file is improtected will precede 
the filename when the appropriate directory is displayed. 

Example: 

UNLOCK /RAM6/FILE 

Direct Access to the Operating System 
GS^OS (Operation.Code, PathName$, Integer_Array% ( ) 

The GS_OS command makes it possible to communicate directly with the operating 
system of the Apple UGS, GS/OS. 

GS_OS is designed to call individual operations within the operating system. These 
calls can perform a whole assortment of things such as getting volimie information, or 
erasing a volume directory, etc; whatever GS/OS is capable of All of the disk access 
commands executed by Micol Advanced BASIC are done by such calls to GS/OS. 

To make use of this conunand, you will need a GrS/OS reference manual- The one by 
Gary Little mentioned in Suggested Manuals in Part One is quiet suitable. 

GS_OS requires three parameters; a GS/OS call number, a string variable whose 
contents may or m^y not be required, and an integer array which will contain the 
pa]*ameter list required by the GS/OS call. The three parameters are: 

1. The call number is the value required by GS/OS to determine which operating 
system command is needed. This value is an integer literal (either decimal or 
hexadecimal) and must be a value greater than $2000 hexadecimal as the 
GS_OS command only supports GS/OS class one calls. 

2. A Pathname is not required by all GS/OS calls, but PathName$ must appear in the 
GS_OS command. If an Integer_Array% element contains a negative one (-1), 
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the string contained within PathName$ will be used for this call. PathNanie$ 
may be any legal Micol Advanced BASIC string which is also a legal GS/OS 
Pathname, according to the call. 

3. The hst of parameters reqxiired by the call is provided to GS/OS using 
Integer_Array% starting with element zero. One integer array element is equal 
to one word. The size of the integer array must be at least as large as the 
maximum number of words sent or returned by the call and must be so 
dimensioned The left parenthesis is required in the syntax of this command, 

4. If an error occurs as a result of the call, the GS/OS error valxie will be returned in 
location 202 (True _Valiie). A zero indicates that the call was made correctly. 
Any other value signals that an error occurred (or that the call was made 
improperly). Please see Appendix D for GS/OS error codes. 



IMPORTANT 



When long integers are used, the most significant bytes of 
each array element are ignored, and the array is 
compressed into short integers before the contents of the 
array are passed to GS/OS. The array is decompressed 
after the results are returned. 



{Large enough for any purpose} 

{12 class one parameters} 
{Pathname in element 1} 



Example: 

PROGRAM OS_Ex ample 

@ LIST 

INT (A - 2) 

DIM Array (40) 

Array (0) = 12 

Array (1) - -1 

PathName$ « ^/RAM5/File" 

{MaJce the call to GS/OS} 

{$200 6 GetFilelnfo} 

GS_OS ($2006, PathName$, Array ( ) 

IF PEEK (202) = THEN BEGIN {No error} 

FOR Ctr =" 1 TO 20 {Display the result returned} 
PRINT Array (Ctr) 

NEXT Ctr 
ELSE BEGIN 

PRINT "GS/OS error" ;PEEK (202) 
ENDIF 
END 
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NOTE 



The GS_OS command can easily handle GS/OS calls with 
one string. If the GS/OS call you wish to make requires 
two or more strings, you will have to create the GS/OS 
class one strings yourself in some buffer area, and pass 
these addresses within the GS_OS call. But don't worry, 
very few calls require more than one string. 



General File Access 
File Access Number 

The commands within this section require a FUe Access Number This is simply a 
digit (no variables allowed), from one to eight, that you give the file when it is opened. 
This value, rather then the Pathname, is used to access the file for fiirther operations, 

APPEND (File Access Number) 

APPEND moves the file pointer to the end of the open file. Any fiiture reads or 
writes to the file will be firom this position. The File Access Number must be the same 
one that was used under the OPEN, ROPEN or WOPEN command 

Example: 

ROPEN (1) ^^File" {Open an existing file} 
APPEND (1) {Write after end of file" 
PRINT (1) "After old end of file" 
CLOSE (1) 

CLOSE (File Access Number) 

CLOSE will close the file specified by the File Access Number. The File Access 
Nxmiber must be the same one that was used when the file was opened with an OPEN, 
ROPEN or WOPEN command. 

All files must be closed after having been used. The closxire of the files ensures that 
aU data have been transferred from memory buffers to their disk files. An EPrt) or 
STOP will also close all files currently opened. 

Example: 

WOPEN (1) ^^FILE" 
CLOSE (1) 
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FILE (Svar) 

FILE verifies that a file with the corresponding Pathname exists. Svar is the 
Pathname of the file> and may be either a string variable or a string literal, 

FILE is a boolean function which returns TRUE if the file exists or FALSE if there is 
no such file. The t<'* ii^l<^ state may also be assigned to a boolean variable: Flag! = FILE 
(File$). 

Example: 

IF FILE ("/RAM6/aELL0") THEN BEGIN 

ROPEN (1) "/RAM6 /HELLO" 
ELSE BEGIN 

WOPEN (1) ^/RAM6/HELLO'' 

END IF 

The type of jfile may be determined by PEEKing into memory location True^Valiie 
(202) right after using the FILE command. This value is a number representing the file 

type. 

In addition, if FILE is TRUE, the file size, in blocks of 512 bytes, will be returned in 
locations 204 and 205 in LSB, MSB order; in location 212 and location 213 is stored the 

Auxiliary file type. 

Example: 

File_Exists! = FILE (InputFile$) 
IF File_Exists! THEN BEGIN 
FlleType% = PEEK (202) 
IF FileType% ^ 4 THEN BEGIN 

PRINT ^"The file '^' InputFile$; '' is of type TXT" 
ELSE BEGIN 

IF FileType% = 176 THEN BEGIN 

PRINT '"The file " ; InputFile$; '' is of type SRC" 
ENDIF 
ENDIF 
ELSE BEGIN 

PRINT InputFile$;" does not exist" 
ENDIF 

GET (File Access Number) Svar 

GET will read characters, one at a time, from disk and place the character into Svar. 
The File Access Number must be the same one that was used when the file was opened 

If the end-offile marker is encoxmtered during a GET, the variable waiting for a 
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value will be undetermined, whereas the end-of-file flag will be set to TRUE, 

Example: 

IF FILE ("File") THEN BEGIN 
ROPEN (1) ^^File" 
REPEAT 

GET (1) Char$ 

IF NOT EOF (1) THEN PRINT Char$; 
UNTIL EOF (1) 
CLOSE (1) 
END IF 

INPUT (File Access Number) Var [{,Var}] 

INPUT functions like the keyboard based INPUT statement except it accepts data 
coming &t)m a file instead of the keyboard* 

The Pile Access Number must be the same number that was used when the file was 
opened Var may be any simple or array variable type except boolean. 

As with the keyboard INPUT command, the data read firom the device must 
correspond to the type required by the variable in the variable list. 



WARNING 



INPUT is only suitable for reading text files. Note that 
the only delimiter for a string input is the carriage return 
(ASCII 13). Commas (,) and semicolons (;) are regarded 
as data for this purpose. If more than 1023 characters 
are read before a carriage return is encountered, an error 
will be generated. 



Example: 

IF FILE ("/RAM6/File") THEN BEGIN 
ROPEN (1) '^/RAMe/File" 
REPEAT {Read from disJc} 
INPUT (1} String$ 
INPUT (1) Real 
INPUT (1) Integer% 
PRINT Strings, Real, Integer% 
UNTIL EOF (1) 
CLOSE (1) 
END IF 
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OPEN (File Access Number) Svar 

OPEN establishes a link between the file specified in Svar and future commands 
directed at the file, Svar may be either a string variable or a string literal. 

OPEN will check for the existence of the file stipulated in Svar, If the file exists, it 
will simply open the file (perform an ROPEN). If the file doesn't exist, OPEN will 
create a new file with the stipiilated name, then open it (perform a WOPEN), In both 
cases, the file pointer wiU be pointing to the beginning of the file- 
Example: 

OPEN (1) ^VRAMe/FILE" 
PRINT (1) "String" 
CLOSE (1) 

PRINT (File Access Number) [USING Mask$;] Var[{,Var}] 

PRENT and PRINT USING function exactly like their screen-based counterparts 
except they send their data to the disk instead of the screen or printer. 

The File Access Number mxist be the same number that was used when the file was 
opened. Var may be an integer, real or string variable or array. 



NOTE 



TABs will not produce spaces in a text file. 



WARNING 



If the data created with a PRINT are to be read by an 
INPUT statement, then be certain not to suppress the 
carriage return by using a comma(,) or a semi-coIon(;) 
after each variable list. It is best to have one variable per 
PRINT statement 



Example; 

WOPEN (1) ^^FILE" 

PRINT (1) "Output to file'' 
FOR Loop_Ctr% - 1 TO 10 
PRINT (1) Loop_Ctr% 
NEXT Loop_Ctr% 

CLOSE (1) 

The end-of-file marker is pushed forward as each variable's contents are written to 
disk. 



Chapter Seven: Disk Filiag 113 



ROPEN (File Access Number) Svar 

The ROPEN command will open an already existing file and will position the fiQe 
pointer to the beginning of the file. The File Access Number used with the ROPEN 
command must be xised with all the commands referencing the file being accessed later, 

Svar is the Pathname of the file and may be either a string variable or a string 
Hteral. The Pathname of the file being read must exist on the disk being accessed. Any 
attempt to ROPEIN a non-existent file will cause a run time error. 

ROPEN establishes a relationship between the Pile Access Number and the 
Pathname. Without this relationship established, the system cannot know which File 
Access Number belongs to which file* 



IMPORTANT 



File Access Nxunber 8 wiU provide much faster access to 
sequential files than File Access Numbers 1 thorough 7. 
However, because File Access Number 8 maximizes file 
access by reading several file blocks into internal memory 
fi:t>m which the file information is then accessed, it is 
unsuitable for random access files. 



Example: (See GET) 

WOPEN (File Access Number) Svar 

WOPEN will erase any existing file with the same Pathname stipulated by Svar, and 
create an empty file with the specified Pathname. If the file already exists, and that file 
is locked, an error will be generated. Svar may be either a string variable or a string 
literal. 

The File Access Ninnber used with the WOPEN command must be used with all the 
commands referencing the file being accessed. 

WOPEN establishes a relationship between the File Access Number and t^e 
Pathname. Without this relationship established, the system cannot know which File 
Access Number belongs to which file. 

Example: (See PRINT) 

Sequential File Access 
EOF (File Access Number) 

EOF is used to detect the end-of-file marker when a sequential Gle is being read. 
The File Access Number must be a digit between 1 and 8 and must be the same value 
used when the file was opened. 
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EOF is a boolean function and may be assigned to a boolean variable as: Flag! = 
EOF (1). This boolean variable may then be tested like any boolean variable. 

If the end-of-file is encountered while reading a variable's value, the value of the 
variable is undetermined, but the EOF flag will be set to TRUE. 

If you try to test the end-of-file on a file which has not been opened, you will receive a 
run time error. 

Example: 

R0PEN(8) 'VRAM6/FILE" (Get fast access with 8} 
REPEAT 

INPUT (8) String$ 

IF NOT EOF (8) THEN PRINT String$ 
UNTIL EOF (8) 
CLOSE (8) 

Random Access Files 
SEEK (File Access Number) Record Number, Record Size 

SEEK is used to move the file pointer within a random access file, SEEK wiU move 
the end-of-file marker if the position is past the current end-of-file. You may then read 
or write to this file location as you require. 

The SEEK command must be xised before any read or write operation to a random 
access file, otherwise the next read or write operation will be done right ajfter the 
previous read or write. Be certain not to leave out this command if a random access file 
is used. 

You must decide what record size you wish; the record may be any size. Once the 
record size is specified, any record may be accessed within the file; even sub-records 
within the fiJe may be accessed by specifying the correct record size. 

lb access a specific field within a certain record, you may skip the previous fields 
using dummy INPUTs. To do so, each field must end with a c riage return^ If the 
Return characters at the end of each field have been suppressed, then the INPUT 
statement(s) will not be able to read the data since INPUT expects the Return character 
as the end-of-field delimiter. 



NOTE 



The use of a Pile Access Number 8, reserved for use with 
sequential file access, will result in an error during 
compilation. 



When calculating the record size, remember that the Return character also requires 
one byte. 
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NOTE 



SEEK may function the same way as the POSITION 

statement of the Applesoft BASIC interpreter by 
specifying a record size of 1, 



PROGRAM Random_Access 

SOME 

WOPEN (1) *VVoltiine2/File" 

INPUT "Enter record size" ;Size 

REPEAT 

INPUT ^^Enter record niimber" ; Record 

INPUT ''Enter any nuinber'' ; Number 

SEEK (1) Record, Size 

PRINT (1) Number 
UNTIL Niomber = 100 
CLOSE (1) 
HOME 

ROPEN (1} ''/Volume2/File" 
PRINT "^The values entered were;" 
REPEAT 

INPUT "Enter record nuinber "/Record 

SEEK (1) Record, Size 

INPUT (1} Number 

PRINT Nuinber 
UNTIL Nuinber = 100 
CLOSE (1) 
END 



NOTE 



From the programmer's standpoint, the only difiFerence 
between a sequential file and a random-access file is the 
use of the SEEK command. 
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Chapter Eight 

Control of Flow 

Overview 

Unless special action is taken, each program statement will execute after the 
preceding statement has finished execution* Very few programs would have any real 
worth if this linear program flow could not be altered. 

It is the purpose of this chapter to discuss the methods available ujider Micol 
Advanced BASIC to direct program flow in an appropriate manner. In this regard, Micol 
Advanced BASIC is one of the most powerful languages for any computer. Use these 
comjnands wisely and your programs will be something to be proud of 

Program Termination 

The termination statements are designed to end the execution of a program; control 
passes out of the program. 

External Flow 

RUN Pathname 

lb execute another Micol Advanced BASIC program or a GS/OS application, use the 
RUN command. Pathname must be the Pathname, including the ".LNK7' extension, if 
any, of the program. Pathname may be a string Hteral or string variable. The file must 
be online at execution time or an error will be issued. 

Examples: 

RUN '^MAB.LNK" 
Path_NameS - '^ FINDER"' 
RUN Path_Naine$ 

Flow Interruption 
END 

END terminates the program's execution, and returns control to the Command Shell 
(if the program was entered fix>m the programming environment). 

END may be placed anywhere in a program. END closes all open files, firees all 
memory, and sets the screen to text mode. 
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NOTE 



Although the Compiler automatically generates an END 
at the end of the program code, it is recommended to 
conclude all programs with END for documentation 
purposes. 



IMPORTANT 



In any program that was launched with the Finder, END 
returns control to the Finder. If the program was started 
as a TumKey system, a System Death will be performed 



Example: 

PROGRAM EXAMPLE 

PRINT ""This is a sample program" 

END 

STOP 

STOP is identical to END except it prints the line nnmber where the program 
halted STOP'S primary function is in debugging. 

Example: 

PROGRAM Example 

PRINT '^This is a simple program" 

STOP 

BYE 

BYE terminates the execution of the program and rettims control to the program 
launcher (even if the program was started from the Command Shell). BYE performs 
what is called a ProDOS QUIT 



NOTE 



When a TumKey system terminates, it is usually to a 
System Death, and the computer will have to be rebooted 
to continue running. If you are creating a TumKey 
system, and a BYE should execute, the booting program 
will re-execute instead of a System Death. 



Example: 

PROGRAM Hello 
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HOME 

PRINT ''Hello" 

BYE {Return to the Program Launcher} 

Branching 

Branching consists of unconditional and selective branching. With unconditional 
branching, the flow will be altered exactly as specified by the control structure. With 
selective branching, the branch will be based upon a condition previously determined. 
With selective branching, if the conditions are not right, the flow will not be altered at 
all 

With branching, control is directed to another area of the program. Careless use of 
this construct may cause havoc in your programs. For this reason, it is recommended 
you avoid branching as much as possible. Ideally, branching should only be done in error 

handling. 

The Routine Declaration 
ROUTINE Id 

Before we can discuss branching, it is necessary to discuss a little about Routine 
declarations. This topic wUl be covered again in the next chapter in more detail 

Whenever you wish to branch to another line with the use of GOTOs, it is possible to 
branch to a mnemonic name instead of a line number In order to do this, you must first 
declare the area of code you wish to branch to with a ROUTINE name. The syntax is 
simply the keyword ROUTINE followed by a unique identifier This identifier has the 
exact same syntax as a simple variable and may be an existing variable name. 

Ehiring compilation, the Compiler checks for the existance of duplicate ROUTINE 
names. If a second ROUTINE name is detected, an error will be issued. 



WARNING 



If you are segmenting your program, then you may not 
give any ROUTINE name that has already been declared 
within a previous segment. The Compiler has no way to 
distinguish between identical ROUTINE names in 
different segments. 



Unconditional Branching 

Unconditional branching takes the program flow to the statement indicated. The 
abusive use of unconditional branching may considerably reduce the legibihty of a 
program, so its use should be avoided whenever possible. 
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The Dreaded GOTO 

GOTO Identifier 
GOTO Line.Niimber 

GOTO forces the program flow to the Une indicated- If the reference line does not 
exists the linker displays the message "Undefined hne or subroutine". When a GOTO 
makes a reference to a line number (not recommended), the line number is treated as a 
ROUTINE identifier. 



NOTE 



The use of GOTOs is recommended only in recovery from 
an error. lb disable GOTO, use the NOGOTO compiler 
option. 



Example: 

IF Number = 5 THEN GOTO Routine_Naine 

ENL 

ROUTINE Routine_Name 

END 

Selective Branching 

Selective branching may be used when three or more selections are needed* The use 
of this option is not recommended as it can lead to problems in determining the program 
flow, if errors arise. The multi-decision CASE_OF is probably a more appropriate 
structure, and its use is recommended. 

The ON..GOTO Statement 

ON Aexpr GOTO Identifier [ {4dentifier} 1 

ON Aexpr GOTO Line_Number [ {, Line_Number) ] 

ON,, GOTO branches to a specific statement or hne depending on the value of Aexpr 
between the words ON.,GOTO. If Aexpr is real, the value is truncated before the branch 
is taken. 

Aexpr is evaluated If the value is less than one or greater than the number of 
identifiers or Une numbers, the program flow will continue with the statement following 
the ON,.GOTO, Otherwise, the flow wiQ be directed to the sequential label or Une 

determined by the result 
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Example: 

PROGRAM Example 

HOME 

REPEAT 

PRINT "^Enter a number from 1 to 3 "; 

GET Digit $ 

PRINT Digit$ 
UNTIL INDEX (Digit$, '"123") > 
Digit% = VAL (Digit$) 
ON Digit% GOTO One, Two, Three 
{Exit point for program} 
ROUTINE Finish 

END {End of Program Execution} 
(Selection is handled below} 
ROUTINE One 

PRINT ^^One chicken soup" 
GOTO Finish 
ROUTINE Two 

PRINT ""Two Fetucinni entrees" 
GOTO Finish 
ROUTINE Three 

PRINT ''Three turkey breasts" 
GOTO Finish 

Loops 

Repetitive statements are used to repeat an action until a condition is met, Micol 
Advanced BASIC has four repetitive contro' statements: FOR^NEXT, FORUNTIL, 
REPEAT.UNTrL, and WHILE..WEND. 

Finite Loops 

The statements in this section are useful for loops that have a predetermined 
number of iterations or repeat execution until another condition arises. 

FOR •• NEXT Loops 

FOR Loop Counter = Initial TO Terminal [STEP Increment] 

This statement begiQS with the keyword FOR followed by an integer or real variable 
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as the Loop Counter* The Loop Counter is assigned the value in Initial and then verified 
to see if its value is greater than T&rminal. If Loop Counter's value is greater than 
Iferminal's, the statements within the loop will not be executed and control will continue 
to the statement after the following NEXT. If Loop Counter's value is smaller than or 
equal to Tferminal's value, the statements within the FOR loop will be executed. 

When all the statements in the loop have been executed. Loop Counter will either be 
incremented or decremented and the FOR statement wiU continue until Iferminal's 
value is exceeded* 

When there is a STEP Increment, if the result of Increment is positive, the value of 
Increment is added to the Loop Counter, If the result of Increment is negative, the 
positive value of Increment is subtracted fi^m Loop Coimter, If STEP is not specified, 
the iQcrement is always a positive 1, 

NEXT Loop Counter 

NEXT followed by a Loop Counter signals the end of a FOR loop. The Loop Counter 
must match the one used in the previous FOR statement- 

If; during compilation, a FOR statement is without its matching NEXT, the 
Compiler wlQ issue an appropriate error message at the end of compilation. 

Example: 

FOR Loop_A% = 1 to 10 

FOR Loop_B% - 1 TO 10 

PRINT ''Loop_B = "; Loop_B% 

PRINT "Loop_A - "; Loop_A% 

NEXT Loop_B% 
NEXT Loop^% 

Please note the following rules for FOR,«NEXT loop construction: 

1. The loop will not be entered if the loop counter's value is already satisfied. 

Example: 

FOR Loop_Countr :% - 10 TO 9 

PRINT Loop__Counter% 
NEXT Loop_Counter% 

2. The NEXT statement must contain the same variable used as the loop counter in 
the previous FOR statement, otherwise an error will occur during compilation, 

3. A loop cannot be "exited" by changing the value of the loop counter. The value of 
the loop counter cannot be changed since the actual loop coimter's value is 
maintained elsewhere. If any attempt is made to reassign the loop coimter 
within the FOR^.NEXT loop, the loop counter will be reassigned the value it 
otherwise would have at the top of the next iteration of the loop. 

4. There may be only one NEXT for each FOR, A Une of code like IF Value = 10 
THEN NEXT Ctr is not aUowed in Micol Advanced BASIC. 

5. The terminal expression is calculated each time at the top of the loop. The FOR 
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loop may end prematurely if a variable is used for the Tbrminal value and this 
variable is being reassigned inside the loop. Watch out for an unintentional 
reassignment. Also, if the terminal expression is somewhat complicated, it may 
eat up valuable execution time. It is preferable to assign that expression to a 
dummy variable just outside the loop, and use this dummy variable as the 
terminal value within the FOR»NEXT loop. 

Example: 

FOR Ctrl% = 3 TO 32000 STEP 2 
Duinrny% = SQR (Ctzl%) 
FOR Ctr2% = Ctrl% TO Duinmy% STEP 2 
IF Ctr% MOD Ctr2% = THEN BEGIN 

DuiTimy% =- 1 {Stop the inner loop} 
END IF 
NEXT Ctr2% 

IF Durr[iTLy% > 1 THEN PRINT Ctr2% 
NEXT Ctrl% 

Be certain the variable (Dimuny%) is not unintentionally changed within the active 
FOR, J»JEXT loop as the loop may not act as desired, 

6. Never use a GOTO to exit a FOR»NEyr loop, otherwise the pointers necessary for 
the functioning of FOR, .NEXT statements will not be reset correctly. The 
program may malfunction if this loop is used again. If a FOR., NEXT loop must 

be left prematiirely, use the FOR,*UNTIL loop structure instead. 

7, The use of integer loop counters is recommended, where practical^ as they execute 
much faster than their real counterparts. 

FOR „ UNTH. Loops 

FOR Loop Coimter = Initial TO Terminal UNTIL Relop 

The FOR„tJNTIL structure repeals one or more statements a precise number of 

times or until the specific condition is TRUE. 

This statement begins with the keyword FOR followed by a Loop Counter. The Loop 
Counter is assigned the value in Initial. The Loop Counter is then verified to see if its 
value is greater than the Terminal value. 

If the Loop Counter^s value is greater than the terminal value, the statements in the 
loop will not be executed and control will be directed to the statement following the next 
NEXT. If the Loop Counter's value is smaller than or equal to the Terminal value, a test 
is made to see if the UNTIL condition is TRUE or FALSE. If the condition evaluates to 
TRUE, control is passed to the statement after the NEXT statement. If the UNTIL 
condition is FALSE, the loop is entered. 

When all the statements in the loop have been executed, Loop Counter will have one 
added to its current value and the FOR statement will continue until the value of Loop 
Counter is greater than Terminal or until Relop become TRUE. Loop Counter is always 
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incremented by one. 

As with the FOR.. NEXT loop conatruct, this statement must also be closed by a 
NEXT statement with a matdiing Loop Coimter, The pertinent rules described above 
for FOR loops also apply here. 

Example: 

FOR Loop_Ctr% - 1 TO 10 UNTIL Aniinal$ = ^^cat" 
INPUT "^Enter any animal's name ";Animal$ 
PRINT ""The ";AniinalS;" is a fine animal" 
AniiTial$ « LOWER$ (Animal$) {Need lowercase for test} 

NEXT Loop_Ctr% 

FOR. J^XT and FOR.UNTIL loops may be nested. The maximum nesting is 20 
levels deep. 

Examples: {Notice the nesting order} 

FOR Out_loop_Ctr% - 1 TO 10 
FOR In_loop_Ctr% - 1 TO 10 

PRINT ^In_loop_Ctr - '';In_loop_Ctr% 
PRINT *'Out_loop_Ctr - ";Out_loop_Ctr% 
NEXT In_loop_Ctr% 
NEXT Out_loop_Ctr% 

This second example will show an alternate way of writing nested FOR,.NEXT 
loops, but the logic is also more difficult to follow 

FOR Out_loop% - 1 to 10: FOR Inloop% - 1 TO 10 

PRINT ^Inloop = ";Inloop%: PRINT **Out_loop - ";Out_loop% 

NEXT Inloop%: NEXT Out_loop% 

Examples of what NOT to do are : 

FOR i - 1 TO 50 FOR j = 1 TO 10 

PRINT i, j NEXT i 
NEXT j {Misplaced loop variables} 

Conditional Loops 

Conditional loop structures will execute the statements inside the structure until a 
particular condition does or does not arise. 
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REPEAT Loops 

REPEAT 

Statement 

[{: Statement}] 
UNTIL Relop 

The REPEAT„UNTIL structure executes the stateinent(s) enclosed between these 
keywords until Relop is TRUE, The statement(s) in the loop will always be executed at 
least once. The program flow continues after the UNTIL statement 

Example: 

REPEAT 

INPUT "^Enter any animal's naine; ";Animal$ 

Animal? = LOWER$ (Animal $) 

IF Animal$ <> '^cat" THEN BEGIN 

PRINT ''The ";Animal$;" is a fine animal" 

END IF 
UNTIL Animal$ = ''cat" 

WHILE Loops 

WHILE Relop 
Statement 

[{: Statement}] 
WEND 

The WHILE. .WEND structure executes the statement(s) enclosed between these 
keywords as long as Relop is TRUE, The statements) in this loop will not be executed if 
the expression is not initially TRUE, The program flow continues after the keyword 
WEND (for WhileEND). 

Example: 

Animal$ - ^" {Make certain loop is entered} 
WHILE Animal $ <> '^cat"' 

INPUT ^Type any animal's name"; Animal$ 

Aniinal$ - LOWER$ (Animal$) 

IF Animal$ <> ^^cat" THEN BEGIN 

PRINT "The ";Animal$;" is a fine animal" 

ENDIF 
WEND 

The REPEAT,.UP^IL and WBILE..WEND structures may be nested to a 
maximum of 20 levels each. 
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Chapter Nine 

Modularization 

Overview 

When a project becomes a large programming task, it becomes necessary to break 
this task into smaller portions, mating this project easier to conceive. This method 
appUes the old maxim: "Divide and Conquer," 

A large program may be divided into modules. A module is like a small program that 
may be executed whenever needed. Each module performs a specific task. Breaking a 
program into small, easy-to-maintain portions is called modularization. 

Not only does modidarization simplify the programming task, it also has the 
advantage of creating routines that may be re-used by other programs. 

A module is a very important construct to the concept of structured programming. 
Once control is passed to a module, unless an unforeseen circumstance occurs, control 
will return to a known location. 

Advantages of Modularity 

1. Ease of conception. It is easier to create an ensemble of short and simple 
modxiies than a long and linear program. Each module will perform a certain, 
well-defined task. 

2. Maintainance. Because each module performs a single well-defined task, it is 
relatively easy to debug and modify this module as the need arises, 

3. Portability. The modules written may be as independent as possible fi-om other 
modules. Thus a module may then be used in another program with no or very 
few changes. 

4. May be written by different programmers. Once the task to be done is well 
defined, the modules may be written by more t' in one person. After the 
modules are written, they also may be individually tested. 

Module Types 

Micol Advanced BASIC has three different types of modules: the Routiae, the 
Function and the Procedure* 

A Routine is probably what you are already familiar with. A Routine is the typical 
BASIC "subroutine". All variables are global (available to the entire program), and 
parameters are not passed to it. Control is passed to the Routine with a GOSUB or 
PERFORM statement and control is returned through a RETURN statement placed 
ideally at the end of the Routine. Unlike most BASICs, a Routiae in Micol Advanced 
BASIC may be given a name with which the Routine may be later referenced. 
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A Function is a module which returns a numeric result. The Function may have both 
local and global simple variables, accepts one or more parameters and always returag a 
single numeric value* A Function is given a name and is implicitly called within an FN 
statement. Control is not retuumed until the end of the Function is encountered. 

A Procedure, like a Function, has both local and global simple variables and accepts 
parameters, Control is passed to a Procedure by means of a GOSUB, and control is 
returned following the Procedure call. Values that need to be shared between a 
Procedure and the main body of the program are shared by means of parameters passed 
by address or by global variables declared earlier in the main program body. 

Module Identification 

As described under ROUTINE names in the previous chapter, all Routines, 
Procedures and Functions may have distinct identifiers. 

The Compiler saves the module names declared after a FUNC, PROC or ROUTINE 
reserved word during compilation. If duplicate module identifiers are found, the 
Compiler will report an error* 

If you attempt to reference a Fxinction, Procedure or Routine within your program 
which you have not defined, during the linking phase> you will receive the message, 
^TFndefined Line or Subroutine" error. Since the Linker has no way of knowing at which 
line this error occurred, you will need to use the Source Code Editor to locate the 
undefined Routine. 

Program Order with Modules 

PROGRAM Identification 

ALIAS ''UNTIL 1 - 2" =- "FOREVER" 

INT (I-N) ; STR (S-Z) 

DATA statements 

DIM statements 

DECLARE Boolean!, Intviger%, Real&, String$ 

Function Declarations 

Procedure Declarations 

Main Program Body 

Routine Declarations 

END 

The above list of declaration statements should be followed to ensure a structured 
program. 
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Routines 

ROUTINE Identifier 

[{ Statement (s)}] 
RETURN 

A Routine is declared by using the reserved word ROUTINE followed by an 
identifier 

The body of the Routine may contain any legal executable statements: DEM, DATA 
aad compiler directives are not executable statements. 

RETURN marks the end of the Routine, and tells the program to retiim to the 
statement following the GOSUB which caused the branch to this Routine. Only one 
RETURN should appear in a Routine. 

RETURN must never be used to end a Procedure or Function as the Compiler wiU 
return an error if so attempted. 

A Routine module is called by means of a GOSUB statement followed by the 
identifier of the Routine- 

If the return stack is empty when the RETURN is executed^ the message "RETURN 
without GOSUB error^ is displayed when the error occurs at run time. 

AU variables included in a Routine are global and may be used by other Routines. 



WARNING 



If the normal program flow reaches a Routine, the 
Routine will execute. This must be avoided. For this 
reason, Routines should be placed after the main program 
body, so they will not be executed without being explicitly 
called. There should be an END statement at the end of 
the main program body to stop the program flow. 



Example: 

GOSUB Box 
END 
ROUTINE Box 

PRINT ^In subroutine' 
RETURN 



Functions and Procedures 



As in the Pascal and C languages, Micol Advanced BASIC has the concept of 
Procedures and Functions that are separate fix)m the main body of the program and that 
may receive values as parameters. 
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General Rules 

A program may have a maximum of 127 Functions or Procedures. The Functions 
and Procedures may reside anywhere in the program, but it is best to declare them all at 

the top of the program. 

Unlike a Routine, a Procedure or Function will not execute by simply letting the 
normal program flow reach the Procedure or Function: it must be called Also, unlike a 
Routine, a Function or Procedure may have both local and global variables and accept 
values as parameters. 

Nesting of Procedures and Functions is not allowed. 

Global and Local Variables 

Global Variables 

A global variable is a variable that may be used and modified by any part of the 
program. Any variable declared at the top of the program outside a Procedure or 
Function is always globaL Arrays are always global. This means the entire program is 
able to access any array element* 

It is sometimes necessary for the entire program, including Procedures and 
Functions, to be able to **see'' certain variables. Whenever a variable is declared outside 
of a Procedmre or Function, but before this Function or Procedure, any subsequent code, 
including Fimctions and Procedures, will have access to this variable. The variable is 
declared simply by being used; initializing the variabl€(s), or placing it in a DECLARE 
statement is all thafs necessary. 

Example: 

PROGRAM Global_Test 

{Variable Global^ may be used by the Procedure} 

Global& - 567,89 

PROC Example [Reals, Integer%] 

PRINT Real& 

PRINT Integer% 

PRINT Global^ 
ENDPROC 

GOSUB Example [100.1, 123] 
END 

Local Variables 

Any variable declared within a Procedure or Function is local to that Procedure or 
Function only if that variable has not been declared globally before this Procedure or 
Function- 
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By locals we mean that only the Fxinction or Procedure in which the variable is used 
will have access to it. Neither the main body of the program, nor another Function or 
Procedure can see the variable. T\vo variables within two Functions or Procedures may 
look the same, but in reality these variables are different. 

Using local variables has the great advantage that the value of a variable with the 
same name outside the Fimction or Proceduire is not accidentally changed by the 
program. 

Values may be shared outside the Function or Procedure only if a parameter is 
passed by address or a variable has been declared earlier as global. 

If the LIST or PRINTER compiler option is in effect, a number sign (#) wiU precede 
the names of local variables in the Symbol Table listing (displayed after the compilation). 

Example: 

PROGRAM Global_Test 
PROC Example [Nuinber%l 

PRINT NuiTiber% 
ENDPROC 
Nuinber% = 567 
GOSUB Example [123] 
PRINT Number% 

In this example, the local variable Number% within the Procedure will have a value 
of 123, and the global variable Ntmiber% outside the Procedure will have a value of 567, 

The Optional Parameter List 

Values may be passed to a Function or Procedure by means of parameters. 
Parameters are variables within a Function or Procedure that will contain a value 
passed to it after it has been called, A parameter list is the series of values sent to the 
Function or Procedure when the Function or Procedure is being called. Both parameters 
and parameter Hsts are enclosed in brackets. 

The rules for the declaration of the parameters are the same as those for any other 
variable. For aU practical purposes, the number of parameters that may be passed is 
unlimited. 

Each parameter will have a corresponding value passed to it when the Function or 
Procedure is being called. A strict one to one correspondence exists between the type of 
value passed and the receiving parameter; they must be of the same data type. 

Parameters may be simple variables of boolean, integer, real, or string. Parameter 
lists may be arithmetic expressions or variables, string variables and literals or booleans 
which may also be the reserved words TRUE and FALSE. 

A real literal, if passed in the parameter list, must have its fractional part explicitly 
written, so that the Compiler knows whether a real or an integer literal is intended. If 
the real value has no fractional portion, you must specify a .0 as in 123.0. 

If a mismatch occurs between the parameter type and the passed value type, an error 
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will occur during execution* For example, if a real expression is passed as the first value 
to a Function, the first corresponding parameter must be a real variable; the same 
applies to integer, string or boolean parameters. 

Ways of Passing Parameters 

Each parameter that is passed to either a Procedure or Fxmction may be passed in 
one of two ways: pass by address or pass by value. 

It is important to understand the difference, as this can affect the program's logic. 
People familiar with either the Pascal or C languages should already have a good 
understanding of these concepts. 

Passing by Value 

lb declare explicitly that a parameter is passed by value, use the reserved word 
VALUE before the parameter declarations. Passing a parameter by value is the default. 
Every parameter encountered up to an ADDRESS reserved word or the end of the 
parameter declarations will be passed by valtie* 

If a parameter is passed by value, only the value in the passing variable is given to 
the Procedure or Function, This means, that under no circumstance will the passing 
variable have its value changed within the receiving subroutine. 

Example: 

PROGRAM Example 

{Passing by Value is default} 

PROC Add [VALUE Gamma] 

Gamma = Gamma + 1 
ENDPROC 
Upsilon = 10 
Gamma =-25 
GOSUB Add [Upsilon] 
PRINT Upsilon, Gamma 

The values printed are 10 and 25. Thus, the value of the parameter passed was not 
modified by the Procedure. When the Procedxire Add was called, the variable Gamma 
was created and the value of the parameter (25) was assigned to it. The incrementation 
Gamma = Gamma + 1 was done with this new variable and not to the variable Upsilon 
where the value was unchanged* The value of Gamma is 25 outside the Procedure 
because the one is added to the local variable Gamma, not the global (but declared after 
the Procedure) variable Gamma. 

Passing by Address 

When a parameter is passed by address, the address of the passing variable is also 
passed to the Procedure or Fxmction so that the passing variable will be modified if the 
parameter is altered within the called Procedure or Function* 
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WARNING 



When an integer or real literal is passed by address, that 
value is made vulnerable to change within the program. 
For this reason, never pass a literal as a parameter when 
it is passed by address as the literal's value in memory 
may also change. 



lb pass a parameter by address, use the reserved word ADDRESS followed by the 
parameters to be passed by address. All parameters up to the end of the parameter 
declaration or the reserved word VALUE will be passed by address. 

Example 1: 

PROGRAM Example 

PROC Add [ADDRESS Gamma] 

Gamma =■ Gamma + 1 
ENDPROC 
Upsilon =- 10 
Gamma =» 25 
GOSUB Add [Upsilon] 
PRINT Upsilon, Gamma 
END 

The values printed are 11 and 25 respectively. The value of the passed parameter 
Upsilon was modified by the Procedure. 

Note that the local Gamma and the global Gamma still have diHerent values. 

Function Definition 

FUNC Identifier [Parameter list] 

Statement(s) 
ENDFUNC [Variable] 

lb define a Function, use the reserved word FUNC followed by any unique, legal 
identifier. The Function identifier may be followed by an optional list of parameters 
encased in brackets ([]). 

The body of the Function may contain any ]egal executable statements, the same as a 
Routine. 

A Function is terminated with an ENDFUNC. Following the reserved word 
ENDFUNC must appear brackets enclosing a simple variable which contains the value 
which needs to be returned by the Fxxnction. The variable must be of the same type, 
either integer or real, as the calling formula with the FN statement; otherwise, an error 
will occur at run time. 

A Fimction is imphdtly called within a formula by preceding the Function identifier 
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and an optional parameter list by the reserved word FN. 



WARNING 



Do not attempt to access a Function with a GOSUB. If 
you do, you cannot access the value returned by the 
Function. Also, do not use a parameter variable as the 
variable used to retimi the Function value as the result 
may become corrupted. 



If the Function which you try to access does not exists you will be informed during 

the linking phase- 
Example: 

FUNC Square [Param] 

Variable '- Param * Paxam 
ENDFUNC [Variable] {Square} 

INPUT "Calculate the square of what number?"; Digits 
{Function call follows} 
Nuinber - 2 * FN Square [Digits] + 1 

If you enter 5, for example, the Function Square will return 25c 

Procedure Definition 

PROC Identifier [Parameter list] 

Stateinent(s) 
ElMDPROC 

lb declare a Procedure, use the reserved word PROC followed by a Procedure 
identifier. The Procedure identifier may be followed by an optional parameter list 
encased in square " rackets ([]). 

The body of the Procedure may contain any legal executable statements: DIM, DATA 
statements and compiler directives are not executable statements. 

The Procedure must be terminated by an ENDPROC, which ends the Procedure and 
generates an automatic return to the statement following the Procedure call. The 
Compiler will inform you if an ENDPROC has been omitted at the end of compilation. 



NOTE 



If you attempt to use a RETURN in a Procedure, the 

Compiler will issue an error. 



A Procedure may be called only with a GOSUB followed by the Procedure identifier 
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and the optional parameter list. The GOSUB must not branch to a Hne within the 
Procedure as unexpected results will occur. If the Procedure does not exist, a message 
will be displayed during the linking phase. 

Explicit Variable Declarations 

If a DECLARE is used in a program containing Functions and Procedures, every 
subsequent Procedure and Function which contain local variables will need a 
DECLARE. Include the DECLARE following the Procedure or Function definition. 
There is an imphdt DECLARE within the parameter declarations, so no DECLARE is 
required there- 
Example: 

PROGRAM Declare_Test 
PROC Example [Parml, Parm2%] 
DECLARE Reals, Integer% 
Real& - Parml 
Integer% = ParTa2% 
ENDPROC 
GOSUB Example [100.1, 123] 

Passing Control to a Subroutine 
FN Identifier [Parm-l, Parm-n] 

A Function cannot be called expHdtly as a Routine is called, but must be called 
implicitly within a mathematical formula. 

In order to call a Function and have it return a value, within the formula where the 
value is required, insert the keyword FN followed by the Function name followed by the 
optional parameter list. In effect, the Function is treated as a sort of variable. 

Example: 

Number = 100 + 32 * FN Square [Farm] / 22 

GOSUB Identifier [Parm-1, Parm-n] 
GOSUB Line^Number [{, Line_Number}] 

GOSUB is used to pass control to either a Routine or Procedure. If control is given 
to a Routine, control is returned with a RETURN statement. If control is given to a 
Procedure, control is only returned at the end of the Procedure by an ENDPROC- In 
both cases, the execution will continue after the statement following the caUiug GOSUB. 



Part Three: The Advanced BASIC Language 



134 Chapter Nine: Modularization 

Example: 

GOSUB Label 

PRINT ""Program will resume here'' 

END 

ROUTINE Label 

PRINT "Now in subroutine" 
RETURN 

POP 

POP is the enemy of structured progrataming. POP removes the latest GOSUB 
address from the stack. This caa be very dangerous mating it difficult to determine 
where an error occurred 

Although some use for POP can be found, the use of POP is not encouraged as it 
may lead to chaos in your programs. POP was retrained solely for compatibility with 
Applesoft BASIC. 

The NOGOTO compiler option may be used to disallow the use of POP. 

PERFORM Routine_Id UNTIL Relop 

A PERFORM executes a Routine continuously until the Routine sets the Relop 
following the UNTIL to TRUE. 

As with a GOSUB, a RETURN is expected at the end of the called Routine to cause 
a return to the PERFORM statement. 

Example: 

PERFORM Animals UNTIL Aniinal$ = '"cat" 
END {This statement is necessary} 
ROUTINE Animals 

HOME {No offense to cat lovers} 

INPUT '"Type in any animal's name ";Animal$ 

Animal $ = LOWER$ ( Animal $) 

IF Anijnal$ <> "^^cat" THEN BEGIN 

PRINT '"The ";Animal$;" is a fine animal" 

END IF 
RETURN 
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Computed Routine Selection 

ON Aexpr GOSUB Routine_Idl [{,Routine_Id(n)}] 

The ON„GOSUB structure works in a similar manner to the ON..GOTO structure. 
ON..GOSUB also allows you to use named Routines. Based upon the result of Aexpr, 
the proper module identifier will be used. 

If the result of the expression is one, the first label in the list will be used. If 
expression is two, the second label in the list will be used, etc. 

If the value is none of the above possibilities, the first sequential statement following 
ON,.GOSUB will be taken. As with any GOSUB to a Routine, when the system 
encounters a RETURN, the nest statement following the computed GOSUB will be 
executed. 

Example: 

INPUT '^Enter a value between 1 and 3 ";Integer% 
ON Integer % GOSUB One, Two, Three 
END 
ROUTINE One 

PRINT "One" 
RETURN 
ROUTINE Two 

PRINT ''Two" 
RETURN 
ROUTINE Three 

PRINT ''Three" 
RETURN 

Module Library Usage 

A library of modules is a collection of often used Pionctions and Procedures that may 
be used in several programs. 

Why create a Ubrary of modules? Because you don't want to keep reinventing the 
wheel. Using a library of modules in your programs give them consistency and makes 
your programs easier to develop and maintain because the modules are already written 
and debugged. 

Creation of a Library of Modules 

First, you must decide what Procedures or Functions you require for future use. Be 
certain each subroutine is completely reliable and thoroughly commented. 

Create a subdirectory on a suitable volume and save the soxirce code of the 
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subroutines to a suitable filename under this directory. 

When you wish to use a Function or Procedure from this library, make use of the 
INCLUDE statement described below. 

INCLUDE Pathname 

lb include a module in a program, add the line INCLUDE Pathname in the source 
code file. Pathname indicates the path to a source code file (of type TXT or SRC). 
Pathname may only be a string literal. 

The INCLUDE statement may appear anywhere in a program after the compiler 
directives. An INCLUDE file may have DATA and array dedaration statements but the 
DATA and DIM statements must still appear in their established order. 

The file being read in must be available (online) at compilation time. When the 
Compiler detects an INCLUDE statement, it looks for a file with the specified 
Pathname and starts reading it as though it were included inside the program itself. 
The Compiler displays the message "INCLUDING pathname^ each time it detects an 
INCLUDE statement. 

Using the INCLUDE statement also has the advantage of having only the necessary 
program code in the Editor, saving the Editor's work space for the code specific to your 
application. 



IMPORTANT 



Make sure your module has been thoroughly debugged 
before you include it in your program as the sequential 
line number information is firozen at the hne of the 
INCLUDE statement and resumes only after the module 
has been read. Run time errors may be difficult to detect. 



Example: 

INCLUDE 'VMicol.Adv,BASIC/L±brary/Math, Routines" 

Recursion 

Recursion is an important topic in computer science. Those of you who have studied 
computer science at the college or university level are already well aware of this fact. 
Those of you who are planning to study computer science wUl soon be finding this out for 
yo\irselves. What is recursion, and why is it so important? 

Recursion is the act of stipulating something in terms of itself. We have all heard it 

said, "a rose is a rose is a rose"". This, in a way, is a recursive definition of a rose- The 
rose is defined ia terms of itself. 

The concept of recursion is not something we deal very often with in our daily lives as 
the previous definition of a rose proves. Not many things around us can be defined ia 
terms of themselves. 
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Mathematics has some use for recursion though. The most common example of a use 
for recursion in mathematics is the definition for the factorial of a number: N! = N * ( N - 

1)! 

This formula translated is: the factorial of a number N is equal to the number N 
times the factorial of the number N minus one. As you can see, the factorial of a number 
is defined in terms of lower orders of itself. If we add to this the definition that when N 
reaches its lowest allowed value of one, that N! is equal to 1, we have a complete 
recursive definition for factorial. 

There is much in computer science that can be defined in terms of itself This 
programming language, Micol Advanced BASIC, was designed with a parse table that 
has many features defined in terms of themselves. 

As with the definition of factorial above, the definition must be complete, or our 
recursive definition is worthless. If factorial had been left undefined for its smallest 
value of one, we could not have m^de use of it. One minus one is zero, and anything 
multiplied by zero is zero. 

Because much of what is defined in computer science is defined recursively, it is only 
natural that computer scientists would like programming languages that allow them to 
express the solution in the manner in which they have laid out the problem in question. 
This is the principal reason recursion in programming languages is so stressed in 
computer science. 

But, recursion in programming languages suffers some severe problems which we 
will now demonstrate. Let us take the definition for factorial jiist given and program it 
in Micol Advanced BASIC making use of reoirsion. You will soon see why recursion 
might be desirable, and also why it is often not the best way to solve a problem. 

Example: 

PROGRAM Recursion 
FUNC Factorial [N] 

IF N <= 1 THEN BEGI^ 
Factorial = 1 

ELSE BEGIN 

Factorial ^ N * FN Factorial [N - 1] 

END IF 
ENDFUNC [Factorial] 
{Start of Program} 

HOME INPUT '^Take the factorial of what number ? "; Number 
Factor - FN Factorial [Number] 

PRINT "The factorial of "/Number; " is "/Factor 
END 

As you can see, the function Factorial looks very much like the mathematical 
definition for factorial. This function will continue to call itself until N is less than or 
equal to one, at which time it will simply imwind the stack, successively returning 
another value for Factorial [N - 1]. 
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One problem has to do with implementation of recursion under the programmiag 
language being used. How is the parameter N treated by the language? If the 
programming language does not reinstate the previoiis value of N as the retiim stack 
unwinds, as Micol Advanced BASIC does, the recursive function will not act as desired 

Another problem is that we are only looking at the theory and not at the real world of 
programming. In the real world, there is much that goes on behind the scenes in the 
execution of the programming language to maintain these calls. For example, each time 
the FN statement is executed^ a run time stack must be saved and then reinstalled after 
the return firom the call. There is also a certain overhead with the passing of each 
parameter, etc. Factorial coxild be programmed more effectively using a simple loop 
instead of recursion. 

A question once asked on a final exam in a computer science class was: True or false, 
anything that can be programmed in a loop can be programmed using recursion?^. 

The author of this question was looking too much at the theory of recursion, and not 
enough at the reality. Recursion is, itself, simply a type of controlled looping, so that the 
question had httle real meaning. Use recursion when it is practical, but do not lose sight 
of reality. 
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Chapter Ten 

Graphics 

Overview 

Micol Advanced BASIC has commands for making great graphics using the 32K 
Super High Resolution graphics screen built into your Apple IIGS. 

Micol Advanced BASIC supports Low Resolution graphics with four lines of text (40 
X 40 blocks) similar to Applesoft BASICs. Micol Advanced BASICs Super High 
Resolution commands control both of the Apple IIGS's Super High Resolution graphics 
modes: 320 X 200, and 640 X 200. 

Low Resolution Graphics 

The Low Resolution graphics mode with text (40 x 40 blocks in 16 colors) is supported 
iQ Micol Advanced BASIC. 

GR 

GR sets a Low Resolution screen of 40 blocks x 40 blocks, GR must be executed 
before any other Low Resolution commands are executed; otherwise further Low 
Resolution graphics commands will have no effect. 

When GR executes, the Low Resolution screen is established and cleared to black. 
The text cursor is moved to the twenty-fourth text liae. 

The point of origin of the coordinate system starts at the upper left comer of the 
screen: 0,0 is the upper left comer 39, 39 is the lower right comer 

Fotir lines of text at the bottom of the screen may be displayed. 

Example; see under BDLTN> 

COLOR = Color_Nimiber 

Sixteen colors may be displayed in Low Resolution graphics. Color^Ninnber ranges 
firom black (0) to white (15), If no color is specified, color 0, black, is used by default. 
This means that if the Low Resolution color is not set, your graphics will be invisible. 
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Value 


1 
2 
3 
4 
5 
6 
7 



Table 3.10.1 - Low Resolution Colors 
Color Value 



Example: see under HLIN. 



black 


8 


magenta 


9 


dark blue 


10 


violet 


11 


dark green 


12 


grayl 


13 


medium blue 


14 


light blue 


15 


HI .IN. 





Color 

brown 

orange 

gray2 

pink 

green 

yellow 

aqvia 

white 



HLIN X^Coordl, X-Coord2 AT Y-Coord 

HLIN stands for Horizontal LINe, HLIN draws a Low Resolution horizontal line 
using the most recently defined color from, point X-Coordl, Y-Coord to X-Coord2, 
Y<;!oord- The X co-ordinates may not be negative or greater than 39, The Y co-ordinate 
may not be negative or greater than 47. If these coordinate values are exceeded, an 
error will occur dxiring execution. Any of the values above may be either integer or real 
expressions. 

Example: 

PROGRAM Show_HLIN 

INT (A-Z) 

GR 

FOR Loopl = TO 39 

FOR Loop2 =» TO 39 

Y_Coord = RND (47) 

X_Coordl = RND (39) 

X_Coord2 - RND (39) 

COLOR = RND (14) +1 

HLIN X_Coordl, X_Coord2 AT y_Coord 
NEXT Loop2 
NEXT Loopl 
END 
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PLOT X-Coord, Y-Coord 

PLOT places a Low Resolutdon block at the location spedfied. The X coordinate may 
not be negative or greater than 39 under Low Resolution. The Y coordinate may not be 
negative or greater than 47; if they are, an error will occur during execution. 

Example: 

PROGRAM Show_Blocks 

INT (A-Z) 

GR 

FOR Down »= TO 47 

FOR Across = TO 39 
COLOR = RND (15) 
PLOT Across, Down 

NEXT Across 
NEXT Down 
END 

SCRN (X-Coord, Y-Coord) 

SCRN stands for screen. It returns the color number of the block specified at the 
location X-Coord, Y-Coord. X-Coord and Y-Coord must be within the Umits specified 
under PLOT. 

Example: 

PROGRAM Show_Pos 

GR 

COLOR -* 13 

PLOT 10, 20 

Color_Num% = SCRN (10, 20} 

VTAB(24) 

PRINT '^Colour Number = ";Color_Num% 

GET Wait$ 

END 

TEXT 

TEXT turns off the Low Resolution graphics mode and turns on the 80 column text 
screen. Follow TEXT with a HOME to remove any garbage text charactei^ left over 
firom the Low Resolution screen. 
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VLIN Y-Coordl, Y^Coord2 AT X-Coord 

VUN stands for Vertical LINe, VLIN draws a vertical line using the most recently 
defined color from point Y-Coordl, X-coord to Y-coord2, X-coorti, The X coordinate may 
not be negative or greater than 39 in Low Resolution mode. The Y coordinates may not 
be negative or greater than 47 otherwise an error will occur during execution. Any of the 
values above may be either integer or real ejqjressiona. 

Example: 

PROGRAM Show_VLIN 

INT (A-Z) 

GR 

FOR Loopl = TO 39 

FOR Loop2 - TO 39 

X_Coord - RND (39) 

Y_Coordl = RND (47) 

Y_Coord2 - RND (47) 

COLOR - RND (14) {Don't want black} + 1 

VLIN Y_Coordl, Y_Coord2 AT X_Coord 
NEXT Loop2 
NEXT Loopl 
DELAY - 1000 
TEXT : HOME 
END 

Super High Resolution Graphics 

The usual Applesoft BASIC High Resolution graphics commaads have heen 
implemented in Micol Advanced BASIC using the much improved Super High 
Resolution (SHR) graphics modes of .he Apple IIGS, While Applesoft's High Resolution 
graphics had a maximum High Resolution of 260 X 192, Micol Advanced BASIC has a 
maximum Super High Resolution of 640 X 200, In addition, the colors under Micol 
Advanced BASIC are vastly improved over their Applesoft coimterparts. 

Please note these important differences between Super High Resolution graphics 
imder Micol Advanced BASIC GS and High Resolution graphics under Applesoft BASIC: 

• SHR has: 

— only one display area 

— a much greater resolution display 

— a greater number of colors 

— a greatly improved color quality 

— a choice of background colors 
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— an easy mix of text and graphics 

— the abihty to use the Apple IIGS ToolBox for drawing 

— no bit-mapped shape tables 

HGR and HGR2 

HGR must be used to set the 320 X 200 Super High Resolution graphic mode. The 
pixels (picture elements) are numbered from to 319 horizontally, and from to 199 
vertically. A maximum, of 16 different colors may be displayed at one time. HGR must 
appear in the program for the 320 X 200 graphic mode to be turned on, 

HGR2 must be used to set the 640 X 200 Super High Resolution graphic mode. The 
pixels (picture elements) are numbered frx)m to 639 horizontally, and from to 199 
vertically, A maximimi of 16 different colors may also be displayed at one time, HGR2 
must appear in the program for the 640 X 200 graphic mode to be turned on. 

With both graphic modes, the graphics color as well as the backgroinxd color is set to 
black Use BKCOLOR and HCOLOR to change the shade of the background and 
graphics colors respectively. 

The point of origin of the co-ordinate system starts at the upper left comer of the 
screen: 0,0 is the upper left comer for both graphics modes. 319, 199 is the lower right 
comer for 320 (HGR) mode and 639, 199 is the lower right comer for 640 (HGR2) mode. 
Initially, the position is set to 0,0 ia both modes. 

Images appeariag in 320 mode are twice as large as the 640 mode, but with half the 
resolution. For example, a box that appears square in 320 mode will appear as a vertical 
rectangle in 640 mode. 

Example: (See example under HPLOT TO.) 
BKCOLOR = Color_Nimiber 

This command allows you to change the background color to any color cturrently 
available (please see table 3,10.2), The commands (HGR or HGR2) that start up the 
Super H' ;h Resolution graphic modes also set the background color to (black). 



NOTE I 

I The effect ofBKCOLOR is not immediate. 



BKCOLOR also changes the background color of the characters displayed using 
DRAWSTR. 

Example: (See example under HPLOT TO,) 
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HCOLOR = Color_Nuinber 

HCOLOR sets the current Super High Resolution color according to Table 3.10.2, 
The default color when an HGR or HGR2 is issued is black, which under most 
circumstances means invisible. You will probably wish to set another color uaing 
HCOLOR before you actually begin to draw. 

In both graphics modes, you have a maximum of 16 colors. We have tried to keep the 
colors in both modes as close to each other as possible. 



Programmers 



By a skillfiil use of the Apple IIGS ToolBox, using Tbol 
number 4 (QuickDraw), it is possible to have as many as 
4096 colors in 320 mode (16 with each pixel). This is not 
possible in 640 mode as special action had to be taken to 
give you 16 colors (4 is the usual number of colors in 640 
mode). Please see Part Five on TbolBox usage for further 
information. 



Table 3.10.2 SHR Colors 



Niunber 


HGK 


HGR2 





Black 


Black 


1 


Dark Gray 


Dark Gray 


2 


Brown 


Light YeUow 


3 


Purple 


Purple 


4 


Blue 


Blue 


5 


Dark Green 


Dark Green 


6 


Orange 


Orange 


7 


Red 


Red 


8 


Beige 


. Pink 


9 


Yellow 


YeUow 


10 


Green 


Green 


11 


Light Blue 


Light Blue 


12 


Lilac 


Lilac 


13 


Periwinkle 


Light Purple 


14 


Light Gray 


Light Gray 


15 


White 


White 
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DRAWSTR (Svar) 

To add text to the SHR graphics, use DRAWSTR. Svar may be a string literal or a 
string variable. The string stipulated in Svar will be displayed starting at the current 
graphics position. You may wish to use HPLOT to move to the position you desire. 

The text will be colored using the latest HCOLOR set, BKCOLOR may be used to 
set the background color of the text. 

If SHR is active, LEN may be used to find the graphics length of the string. PEEK 
True_Valiie (locations 202 and 203) after taking the LEN to find the size in pixels. 

Example: (See example under HPLOT TO.) 

HPLOT X-Coord, Y-Coord 

HPLOT moves the high resolution pointer to the X coordinate and Y coordinate 
stipulated and plots a single point in the latest HCOLOR The maximum X-Coord and 
Y_Coord values are those discussed under the HGR and HGR2 commands. Values too 
large will plot off the screen and no error will be generated. 

Example: (See example under HPLOT TOO 

HPLOT TO X-coord, Y-coord 

HPLOT TO will draw a straight line from the last graphics position to the position 
stipulated using the latest HCOLOR No eixors are generated by this command; values 
greater than the screen will display to the limits of the screen. You may wish to use 
BDPLOT to change the graphics position. 

Example: 

PROGRAM Draw^Box 

HGR2 {set 640 mode} 

HCOLOR ^ 4 {Blue} 

BKCOLOR = 15 {White} 

HPLOT 10, 10 {Draw box starting here} 

HPLOT TO 600, 10 

HPLOT TO 600, 190 

HPLOT TO 10, 190 

HPLOT TO 10, 10 

HPLOT TO 600, 190 

HPLOT 600, 10 

HPLOT TO 10, 190 

{Write message on box} 

HPLOT 190, 50 {Start the message here} 
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DRAWSTR ("This is a big box") 

DELAY = 1000 

TEXT 

END 

This will plot a blue box crossed with an X for about 10 seconds. 
Super High Resolution Shapes 

Once the Super High Resolution mode is set with either the HGR or HGR2 
command and the colors set using the HCOLOR and BKCOLOR commands, it is then 
very easy to draw most figures using the TOOLBOX command 

The four types of shapes you can create are: rectangle, oval, arc, and rounded 

rectangle. 

The three dijfferent modes of drawing are: paint (draws soHd figure), frame (draws 
the outline of the figure only), and erase (draws a figure using the current background 
color). 

For example, to draw a circle, first select the proper graphic mode using HGR or 
HGR2, set the desired color(s), then use the TOOLBOX command to draw the circle. 

When using four basic shapes (Rectangle, Oval, RRect and Arc), the shapes are 
drawn by Tool number 4, QuickDraw II, in an invisible rectangle to determine their si^e 
and shape. QuickDraw II gets the dimensions of the rectangle through the following 
parameters: 

• Min_X (the X value of the left side) 

• Mlq^Y (the Y value of the top) 

• Max_X (the X value of the right side) 

• Max^Y (the Y value of the bottom). 

The Procedures DravKr_Rect and Draw^^Arc below may be used to draw four 
different types of shapes in three different modes in any size. Draw_Rect is used to 
draw the rectangle and the oval while Draw_Arc draws the ap- and the rounded 
rectangle. 

When using the Procedure Draw_Arc to do arcs, Start_Angle is the angle iq 
degrees which the arc starts, with degree being a vertical line , and Aiigle_Length is 
the length of the arc in degrees. 

Td create all this variety with the code presented below, select the correct Procedure 
and change the first parameter passed to the desired value based upon the table on the 
next page. 

Many, many more figures are possible using very similar techniques detailed m the 
manual Programming the Apple IIGS Ibolbox listed in Part One. 
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Table 3.10.3 Pre-Defined Shape Drawing Functions 
Rectangle Oval RRect Arc 



Frame 


83 


88 


93 


98 


Paint 


84 


89 


94 


99 


Erase 


85 


90 


95 


100 



Example: 

PROGRAM Shape_Examples 

INT (A - Z) 

DIM Buffer (10) 

PROC Draw_Rect [Func_Num, Min_X, Min_Y, Max_X, Max_Y] 

LSB » ADDR (Buffer ( ) (Address of buffer} 

MSB = PEEK (202) {Bank of Buffer} 

TOOLBOX (4, 74: MSB, LSB, Min_X, Min_Y, Max_X, Max_Y) 

T0OLBOX{4, Func_Num: MSB, LSB ) 
ENDPROC 

PROC Draw_Arc [Func_Num, Min_X, Min_Y, Max_X, \ 

Max_Y, Start_Angle, Angle_Length] 

LSB = ADDR (Buffer ( ) {Address of buffer} 

MSB - PEEK (202) {Ban}c of buffer) 

TOOLBOX (4, 74: MSB, LSB, Min_X, Min_Y, Max_X, Max_Y) 

TOOLBOX (4, Func_Num: MSB, LSB, Start_Angle, Angle_Length) 
ENDPROC 

{Exainple program begins here} 

HGR {Start 320 Graphics Moae} 

HCOLOR - 15 {White} 

GOSUB Draw_Rect [88, 5, 5, 250, 190] 

DELAY - 1000 

TOOLBOX ($04, $15: $0) {Clear SHR screen for 2nd drawing} 

HCOLOR = 2 {Brown} 

GOSUB Draw_Arc [98, 5, 5, 250, 190, 50, 180] 

DELAY - 1000 

END 
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Joystick and Paddle Controls 

Since joystick or paddle controls are very often used with graphics, this topic is best 
covered in this section. 

PDL (Paddle^Number) 

A paddle is a game controller having only one axis, either X or Y. A joystick comhLnes 
two paddles to control both axis simultaneously. 

PDL returns a value (either integer or real) which is generated by the paddle 
number specified Paddle_Number must be a value firom to 3 inclusive, otherwise a 
run time error will occur, 

A paddle uses a paddle number from to 3. A joystick uses paddle numbers and 1 
or 2 and 3. The value returned varies from to 265. 

lb do consecutive readings on the hand control(s), use real variables with PDL to 
ensure accurate readings. This delay can insure a more accurate reading. 

Paddle and Joystick Buttons 

The buttonCs) on a game controller may be read by PEEKing the appropriate 
locations- Buttons on game controllers return a value > 127 if the button is pushed, and 
< 127 if the button is not pushed.^ 

PEEK (49249) for game controller (this is also the Open Apple key). PEEK 
(49250) for game controller 1 (also the Closed Apple key), PEEK (49251) for game 
controller 2, 

Example: 

PROGRAM Joystick_Check 

HOME 

REPEAT 

VTAB (1, . HTAB (1) 

PRINT ^X - ''; PDL (0.0), 

PRINT ^Y - "; PDL (1) , 
UNTIL PEEK (49249) > 127 OR PEEK (49250) > 127 
IF PEEK(49249) > 127 THEN BEGIN 

PRINT ''Button 1 was pressed" 
ELSE BEGIN 

PRINT '^Button 2 was pressed" 
END IF 



This program will execute until one of the buttons is pushed. 
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Chapter Eleven 

The Sound of Music 

Overview 

The Apple IIGS has perhaps the best sound capabilities of any microcomputer on the 
market today and Micol Advanced BASIC allows you to create some very delightful 
sounds. Music may also be created quite easily by xising just a few simple commands. 
This is the topic of this chapter. 

Audio Output 
BELL 

Use BELL to provide an aural feedback to the user when the program is being used 
improperly or as a warning to a possibly dangerous situation. 

BELL will produce a beep sound through the speaker of your Apple. You may control 
the volume of the beep through the Control Panel of your computer. 

Example: 

BELL: BELL {Ring bell twice} 

Sound 

Each sound comes from a specific sound wave. For example, the sound wave of a 
saxophone is different firom the sound wave of a piano. 

A sound is made by the compression and expansion of the air around us. This 
invisible movement is the vibration of the air. When the vibrations reach our eardnmis, 
our eardrums vibrate which become impulses our brain interprets as sound. 

The number of times a vibration occurs per unit time is called a frequency. The note 
Middle C played on a piano, for example, generates a sound with a frequency of 246 Hz. 

A sound is represented graphically by a waveform. A wave starts with iucreasing 
positive values up to a limit specified and then decreases to negative values with the 
same limit, increases again up to positive values and so on. 

The vertical axis represents the amplitude or the loudness of the sound The 
horizontal axis represents the time. A waveform has a minimum and maximum 
frequency and amplitude. One up and down wave motion is called a cycle. A note is 
measured by the number of cycles per second. 

The sound produced with Micol Advanced BASIC is digitized; that is, numbers are 
fed to the computer and the computer then uses those numbers to make sounds. 
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Waveforms 

The Apple IIGrS generates sounds using three kinds of waves: square waves, triangle 
waves, and sine waves- Square waves create buzzing soimds, triangle waves produce 
another type of buz?nng effect A sine wave makes a pure, clear soimd- Micol Advanced 
BASIC uses a sine wave as the default waveform. 

The Default Waveform 

The default waveform is established when Micol Advanced BASIC is booted This 
waveform is used by the sound making commands of Micol Advanced BASIC and is a 
full wave made of 255 parts numbered from 1 to 255/ 

The default waveform is based on a sine function times 255 from zero to 360 degrees. 
This default waveform produces a pleasant sound and wiU be smtable for most purposes. 

Creatmg your own Waveform 

If you decide that the default waveform is not suitable for your purposes, then it may 
be replaced with another waveform using the WAVE command. 

WAVE = Wave^Numbers 

WAVE places a new waveform into the waveform buffer. This buffer is used by the 
system to store the waveform needed for the NOISE and MUSIC commands described 

later 

The Waveform buffer is 256 bytes long and each value in the waveform may range 
from 1 to 255. A value of zero will be changed to one because a value of zero turns off the 
internal sound generators, 

WAVE must be placed within a loop in order to set the entire Wave buffer. Initialize 

the Waveform Counter by assigning location 42 to zero, then keep assigning values to 
WAVE until location 42 is zero again; i.e. the Wave biiffer is fudl, 

WAVE may be used at any time within the program, but the new waveform wiU not 
be used until the next NOISE or MUSIC command is executed. 

Example: 

PROGRAM Make_Waveform 
INT (A - Z) 
Number = 
Flag! - TRUE 

POKE 42,0 {Init buffer counter} 
REPEAT {Make the wave form table} 
IF Flag! THEN BEGIN 
Number = Number + 4 
IF Number > 250 THEN Flag! = FALSE 
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ELSE BEGIN ■ 

Number ^ Niimber - 4 

IF Number < 5 TH£N Flag! ^ TRUE 
END IF 

WAVE - Number 
UNTIL PEEK (42) - {Until buffer is full} 

Be careful when usiag WAVE, as in the following example: 

WAVE - SIN (Radians %) *- 100 

will almost always place a zero into the waveform buffer as the integer sine is almost 
always zero. Here is an example on how to work aroxind this: 

WAVE = 100.0 ^ SIN (Radians%) 

The first thiag seen by the Compiler after the equal sign is a real nimiber, hence real 
arithmetic will be performed 

Experiment with different values to find the sound you are looking fon 
Unfortunately, some values are unsuitable for the system causing it to crash^ so do not 
be surprised if the system should happen to do just that. Try different functions such as 
cosine multiplied by a factor to get an integer value between and 255. 

Making the Sound 

NOISE (Generator, Pitch, Volume) 

NOISE is used to generate a simple sound. It should be suitable for most sound 
effects. 

Generator is an integer value from 1 to 15 and is the actual generator nximher used 
internally by the computer. 

Pitch and Volume are integer values that may vary fix^m 1 to 255, Each parameter 
may be either an integer literal or an integer variable. A real parameter will be rejected 
by the Compiler 

The pitch is the starting fi-equency used The volume is the loudness of that sound. 

If a NOISE statement with an active generator is given new pitch and volume 

values, that generator will be turned off and restarted using the new pitch and volume. 

NOISE may be stopped with the QUIET or SILENCE command described later. 

Example: 

Generator% « 1 

Pitch% = 80 

Volume% - 100 

NOISE (Generator%, Pitch%, Volume%) 
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Music * 

Micol Advanced BASIC not only allows you to make simple sounds> as just described> 
you can also create rather delightfiil miisic. 

As you might guess, music requires more knowledge and preparation than just 
making simple sounds. 

Instalments 

All music is performed by musical instruments. These miisical instruments may be 
violins, flutes, or even human voices. Each instrument has its own unique sound quality. 

In order to make music under Micol Advanced BASIC, a musical instrument must be 
defined. This instrument may be almost anything you would see in a band or orchestra. 

Default Instrument 

A default instrument has already been defined into Micol Advanced BASIC and 
should be adequate for most pxirposes. You will have to exi)eriment to determine if this 
instrument is suitable for you. 

Creating Other Instruments 

If the default instrument isn't suitable for your purposes, you may create an 
instrument of your own, Micol Advanced BASIC is capable of storing the envelope 
definition of any instrument using the INSTRUM command. 

The instnmient buffer is 44 bytes long. This means that 44 values must be read 
before the new instrument may be used. The proper values for an instrument range 
fi:t>m to 127, 

Unfortunately, it is not a simple task to understand the data that needs to go into the 
Instrument Buffer, Study Table 3.11,1 to imderstand the values that are needed 

INSTRUM = Aexpr 

The INSTRUM command is used to place a new instrument into the Instrument 
Buflfer with the different values needed to duplicate the sound produced by any musical 
instrument. This Instrument Buffer is used by the system whenever you execute the 
MUSIC command 



WARNING 



Be certain of the values you are assigning INSTRUM. 
INSTRUM does no error checking, and if any value is 
inappropriate, the system may crash when the next 
MUSIC command is executed 
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lb fill the Instrument Buffer, set memory location 42 to zero. Then, within a loop, 
keep assigning INSTRUM a value until location 42 is zero again, 

(See the example after Table 3.11-1) 

Table 3.11.1. Instrument Data Structure 

Envelope 

An envelope represents what the soxind woxild look hke if it were drawn on paper It 
may have up to eight segments niunbered to 7, each having a breakpoint and an 
increment value pair. 

The breakpoint value is a byte with a value &t)m to 127, It specifies the volume 
level. The volimie should not be set to zero before the end of the segment or the sound is 
considered done. The last breakpoint is always zero- A difference of 16 in the breakpoint 
value represents a change of 6 decibels (db) in amplitude. 

The increment value is a measure of time indicating the time needed to get to the 
breakpoint volume that uses two bytes. Both bytes range fixjm to 127. The value of 1 
in the low-byte represents a l/256th in value. An increment value of is equivalent to a 
sustained note. The note will play xmtil no generator can play it and the original 
generator producing the note is allocated another note. 

Release Segment 

This integer number from to 7 indicates at which breakpoint the note wiU start to 
fade away The release may occupy several segments, but the last breakpoint is always 
zero. 

Priority Increment 

This value from to 127 indicates at which moment a generator will drop the oldest 
note it is currently playing before playing the new one. 

Pitchbend Range 

This number indicates the number of semitones a note may be raised The accepted 
values are 1, 2 and 4 semitones. 

Vibrato Depth 

This number from to 127 indicates the vibrato effect for a note. No vibrato effect 
occurs with a value of zero. The vibrato should always be set to zero. 

Vibrato Speed 
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This nximber from to 127 controls the rate of vibrato. Higher values produce faster 
vibrato. Set it to zero when vibrato Depth is zero. 

Spare 

This byte is not documented and it may be reserved for future use. Set it to zero. 

aWaveCount and bWaveCount 

A Micol Advanced BASIC instrument has only one wave list per oscillator. Wave A 
and Wave B should always be set to one- 

The default wave count could change in a future version of the language, 

aWaveList and bWavelist 

A wavelist is an array structure of 6 bytes. Since a Micol Advanced BASIC waveform 
has only one wave in each list, set the topKey value to 127, 

WaveList Array Structure 

• topkey 

The Note Synthesizer always plays the note with a topKey value equal or higher 
than the preceding one* The waveform should be stored in increasing topKey 
value. The value ranges from to 127, The last waveform should have a 
topKey value of 127, 
Wave Address 

This is the high byte of the waves address in the Digital OsdUator Chip (DOC) 
RAM, 
' Wave Siase 

Wave Size is set to 256 bytes. Set the number to zero. 

• DOC Mode 

This number represents the size of the sound wave measured in by1;es. One wave 
is used per instruments defined with Micol Advanced BASIC. The mode of 
the DOC chip should always be set to 0, Do not modify, 

• relPitch 

This value is used to time the waveform. The high byte value represents whole 
semitones, the low byte represents fractions of semitones. A value of 1 in the 
low byte equals l/256th of a semitone. 
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Example 

PROGRAM New_Instr\im 

INT (A-Z) - M 

{Instrument Definition) 

{Envelope} 

{Noise} 

DATA 127 {Breakpoint 0} 

DATA 0,127 {Increment value 0} 

DATA 120 {Breakpoint 1} 

DATA 20,1 {Increment value 1} 

DATA 120 {Sustain at 120} 

DATA 0,0 {Zero increment is sustain} 

{Segment} 

DATA {Release to volume} 

DATA 60,120 {Slowly} 

DATA 0,0,0 {Pad with extra breakpoint} 

DATA 0,0,0 {Increment pairs until the} 

DATA 0,0,0 {total is eight} > -^ 

DATA 0,0,0 {End of envelope definition} 

DATA 3 ^"^'-^ {Release starts at 3rd segment} 

DATA 32 {Priority increment} 

{ Pbrange , vibdep , vibf , spare , A, B } 

DATA 2,80,90, 0,1,1 _ 

{topkey, addr, size, Ctrl, pitch} 

DATA 127,7,2,6,0,12 {Halt b, to be swapped in by a} 

DATA 127,7,2,1,0,12 

(End of instrument definition} 

POKE 42,0 {Init Instrument Buffer} 

{Initialize the loop} 

REPEAT 

READ Number 

INSTRUM = Number {Fill one buffer entry) 
UNTIL PEEK (42) = {zero when done} 
{Program continues) 
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NOTE 



The INSTRUM command is an integer command This 
means, that unless the value directly after the equal sign 
is explicitly a real variable or a real number, integer math 
will be used- 



Making the Music 

Now we come to the section where you actually generate the music. Once suitable 
waveforms and instruments have been defined by you, the actual music is generated by 
the MUSIC command 

MUSIC (Generator, Pitch, Volume) 

MUSIC is used to generate musical sounds. By a proper use of the WAVE and 
INSTRUM commands, virtually any instrument may be simulated. In addition, because 
there are 15 generators available, you may have several instruments going at once. 

Generator is a nizmber from. 1 to 14, This number is a relative generator number 
estabhshed by the system, and not the actual generator as in the NOISE command. 

Pitch and Volume may vary fixDm 1 to 127. Each parameter may be either an lateger 
Hteral or an integer variable. 

The pitch is the starting firequency based upon the values you placed into the wave 
table. The volxune is, of course, how loud the music will be made. 

If you do not wish the default waveform with the MUSIC command, then be certain 
to set the new waveform buffer using the WAVE command. 

If another MUSIC command is issued using the same generator, the new sound wiU 
replace the old one. 



NOTE 



The NOISE command cannot be used simultaneously 
with MUSIC. If MUSIC is active, NOISE will be ignored, 
and if NOISE is active, MUSIC will be ignored. 



Example: 

MUSIC (1, 40, 80) 

This example uses logical generator 1 with a pitch of 40 and a volume of 80, 
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IMPORTANT 



The MUSIC command reqxiires the use of an Apple UGS 
Tool located on the system disk Be aware that when the 
MUSIC command is first executed, the booting disk must 
be online so that the approriate Ibol may be loaded. If 
this disk is not online, you will receive a request to insert 
it. The Micol Advanced BASIC system disk marked 
Master Disk comes with this Tool installed. 



Stopping Sounds 

It is not enough to simply create sound or music, you must also be able to turn these 
sounds of£ Very few programs would be suitable with somid running all the time. 

QUIET (Generator) 

QUIET is used to turn off the specified generator and may be used to create pauses 
in noise or musical sequences. Generator is the generator that was used when the 
NOISE or MUSIC command was executed 

Example: 

MUSIC (1, 40, 80) {Start generator one} 

DELAY =10 

QUIET (1) {Silence generator one} 

Txim Them AU Off 
SILENCE 

The SILENCE command turns off all sound generators currently playing. This 
command has no parameters. 

The END and STOP commands also produce the same effect as SU^NCE. 
Example: 

MUSIC (1, 40, 80) {Start generator one) 

DELAY - 1000 

SILENCE {Shutdown generators and tools} 
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Chapter Twelve 

Creating The Human Element 
Overview 

Unlike computers, human beings are not regulated by On and Off. What makes 
humans special is the ability to see the different shades of gray, to make a decision based 
on related information or on a hunch. Programming languages try to imitate this 
randomness using pseudo-random numbers. Micol Advanced BASIC takes this one step 
further by introducing Controlled Uncertainty^^. 

Pseudo Random Numbers 

Pseudo random numbers are not really random, but only appear to be. The only 
random number in the sequence is the first, or the seed as it is called. After that, the 
generator goes through a complex set of calculations to get what appears to be a random 
result, 

Micol Advanced BASIC has two pseudo random number generators: one for integers, 
one for reals, both activated by the RND function. 

Be cautious with the use of RND, It is easy to call the real pseudo random number 
generator by mistake when you want to use the integer generator or vice versa Be 
careful not to call the wrong one since they behave differently 

Integer Pseudo Random Numbers 

Integer% = RND (Aexpr) 

The integer pseudo random number generator is invoked when the assignment is 
made to an integer variable. The ix^^ger RND function yields a pseudo random number 
between and Aexpr inclusive. Thirty-two thousand (32,000) is the largest argument 
that may be passed to RND. w i 

If an INKEY$, INPUT or GET is executed within a program, the integer random 
number generator will be reseeded This reseeded value is an actual random number, 

lb use the integer random generator, do something like this; 

FOR Ctx% « 1 TO 6 

Dice% = RND (5) + 1 {Random values between 1 and 6} 
PRINT ^^Throw # "; Ctr%; ^" of the dice is a ^\- Dice% 

NEXT Ctr% 
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Real Pseudo Random Numbers 

Real& = RND (Aexpr) 

The real RND function yields a floating point pseudo random number between zero 
and one inclusive. The argument is ignored but must be included, otherwifie an error 
will occur during (X)mpilation. 

To use the real random generator, do something like this; 

FOR Ctr% = 1 TO 100 

Real_Randorn& = INT (RND (1) * 100) 

PRINT '"Pass # "; Ctr%;'; is "; Real_Random& 
NEXT Ctr% 

Controlled Uncertainty^^ 

Programming languages usually deal in absolutes of logic. Something is either true 
or false» and actions are always taken depending on this conditioru 

Micol Advanced BASIC goes one step further and gives the programmer the 
possibility to set conditions that may or may not take a certain action based on this 
condition. We feel this is a feature that has many possibilities if intelligently used. 

We call this feature Controlled Uncertainty. It is uncertain because there is the 
possibihty an alternate decision will be made. It is controlled because the decision is 
being made within one of the structured constructs ^ Micol Advanced BASIC, 

When could Controlled Uncertainty be useful? Anytime you wish to program human 
uncertainty within a program. Many things in life are based on assumptions, not facts. 
Any condition that is not absolutely true or false may use this feature. 

Setting the Uncertain Condition 

Controlled Uncertainty may be set using certain settings of boolean variables; 
Usually a boolean variable is set to TRUE or FALSE. Under Micol Advanced BASIC, a 
boolean variable may also be set to DUNNO, DOUBT or BELIEVE. BELIEVE is used 
if the condition is probably true, but there is a chance it is false. DOUBT is used if the 
condition is probably untrue, but there is a possibility it is true- There also exists 
DUNNO. DUNNO is the logical equivalent to a random number generator and wiU 
randomly select one of the otiier four possibiMties. 

If a boolean variable is set to BEUDEVE and then tested, there is about an eighty 
percent chance the condition will be TRUE, about twenty percent chance the condition 
will be FALSE, If a boolean variable is set to DOUBT and then tested, there is about a 
twenty percent chance the condition will be TRUE, and about eighty percent chance the 
condition will be FALSE. 

In addition, booleans set to an uncertain condition may be ANDed or ORed with 
other booleans which will often make one of the other alternatives. We have collected all 
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the possibilities into an uncertainty table which, we display here. 



AND 



Table 3.12.1. Uncertainty Table 



False 



Doubt 



Believe 



True 



False 


False 


False 


False 


False 


Doubt 


Doubt 


Doubt 


False 


Doubt 


Believe 


BeUeve 


False 


Doubt 


Believe 


True 


False 


Doubt 


Believe 


True 


False 


Doubt 


Believe 


True 


Doubt 


Doubt 


Believe 


True 


BeUeve 


Believe 


Believe 


True 


True 


True 


True 


True 



False 
Doubt 
BeUeve 
True 

OR 



False 
Doubt 
Believe 
True 

Example: 

PROGRAM Human_Computer 

HOME 

PRINT "HellOr I'm your Apple computer, "; 

PRINT ""I've been turned off for a while -" 

PRINT '^I do remember the time and the date, "; 

PRINT '^but not your name . " 

INPUT '^What is it again? "; Name? 

Mood! =• BELIEVE 

IF Mood! THEN BEGIN 

PRINT '^Im feeling well today, and "; 

Health! =^ DOUBT 

IF Health! THEN BEGIN 

PRINT '^hope you're feeling fine too." 

ELSE BEGIN 

PRINT ^^certainly hope you're not feeling poorly." 

END IF 
ELSE BEGIN 

PRINT ""I'm sorry, I'm not well today, can^t talk anymore.' 

Polite! ^ DUNNO 
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IF Polite! THEN BEGIN 

PRINT ^Have a nice day "; Name? 
ELSE BEGIN 

PRINT ^Get lost ''; Name$; '' and don't call again!!' 
ENDIF 
END IF 
END 



WARNING 



The statements IF Pla^l THEN and IF Flag! = TRUE 
THEN do not have the same effect when Controlled 
Uncertainty values such as DOUBT or BELIEVE are 
used. If the variable Flag! is assigned to DOUBT and 
Flag! is tested as IF Flag! = TRUE THEN, the variable 
Flag! will never be true, while if the variable Flag! is 
tested as IF Flag! THEN, the variable Flag! will be true 
about 20 percent of the time. 



NOTE 



The condition at which a boolean variable is cinrently set 
may be determined by using the PRINT <Boolean!> 
statement to print the boolean value of FALSE, DOUBT, 
BELIEVE or TRUE. 
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Chapter Thirteen 

Direct Memory Access 
Overview 

This chapter discusses how to look at and change the contents of specific memory 
locations, and manage blocks of memory within a Micol Advanced BASIC program. 

Examining and Changing Memory 

PEEK (Aexpr) 

To see the value of a particular memory location, use the PEEK command where 
Aexpr is the address to be referenced- 

Your computer has memory addresses at least in the himdreds of thousands, 
probably over a million. Unfortunately, if you are using (default) short integers, the 
maximum value an integer can have is 65535. This means that integer PEEKs may 
only be used within bank zero, which usually is to locations in direct page. If you wish to 
access memory locations in higher memory locations, be certain to assign PEEK to a real 
variable. 



NOTE 



The Direct Page area used by the run time Library (not 
by the computer firmware) will be accessed if the value 
passed to PEEK is less than 256. Zero page used by 
Applesoft BASIC and Direct Page are not the same. 



Example: 

Integer% = PEEK (Location%) {Can only access bank zero} 
Real& * PEEK (Location&) {Can access any mernory} 
PRINT PEEK (Locations) {Can access any memory} 

POKE Aexprl, Aexpr2 

POKE may be used to change the contents of the memory location specified, Aexprl 
is the address in memory, Aexpr2 is the value to be stored in the memory location and 
cannot be greater than 255, otherwise, an error wiU occur at run time. 

If a negative integer address is used, POKE will convert the address into a two's 
complement address. 
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If the address passed to POKE is less than 256, the direct page area used by the 
run time Library (not the zero page area used by the computer) will be accessed. 



IMPORTANT 



POKE cannot change memory locations 224 to 255 that 
are reserved in the Direct Page for system \isage- If a 
POKE is made to any of these addresses, an error will 
occur during program execution. 



Example: 

POKE Location%, Niiinber% {Addresses in bank zero only} 

POKE Location^, Number {Can access almost the entire memory} 

Finding the Address of a Variable or Array 
ADDR (Variable [(] ) 

The ADDR (Variable) command returns the address of any variable. If the variable 
is an array, the left parenthesis must be included to inform the Compiler that an array is 
being referenced. 

The address returned is the actual address obtained during execution of the 
program, NOT the relative address displayed by the Symbol Table Dump at the end of 
compilation (if the LIST or PRINTER option is used). 



NOTE 



ADDR, when assigned to an integer variable, will only 
return addresses between ±32767 ($0000-$FFFF) unless 
the LONGINT compiler option is used. If you are 
assigning the result of ADDR to a short integer variable, 
you may fetch the bank number of the address of the 
variable by PEEKing Tme^Value (location 202) of the 
direct page inmifidiatell after executing ADDR, The 
actual address in the bank, if greater than +32767, will be 
represented as a negative number Add 65535 to a real 
variable get the positive value. 



If you are using real values with ADDR, you will get the full address of the specified 

variable. 

ADDR is often used to find tiie address of a buffer used by a particular TboL (See 
Allocating Tbolbox buffers in Part Five.) 
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Example 

This_Addxess& = ADDR {Varia±^le) 
This_Address% = ADDR {Variable) 
Bank_Nuinber - PEEK (202) 
Array_Address& - ADDR (Array ( ) 

Memory Images and Files 

Sometimes it is necessaiy, within a program., to be able to bring^ information from a 
disk file directly into memory. Also, the opposite may be true, memory locations must be 
saved to disk to be used sometime later, perhaps even by another program, 

Micol Advanced BASIC has two commands to accomplish these tasks. You must 
however be very careful, as there is no protection, any part of memory may be accessed. 

BLOAD Svar, Start_Address, Bytes_to_Load 

BLOAD stands for Binary LOAD. Use BLOAD to bring binary data (a 

non-compressed picture or sound information file) into memory. Because there is no 
checking on the file type^ any uncompressed file may be loaded with BLOAD. 

Svar is the Pathname of the file. Svar may be either a string variable or a string 
literal. Start^Address is the address of the first memory location to which the file will be 
loaded. Bytes_to_Load represents the size of the file in b3rtes. Start_Address and 
Bytes_'Ib_Load may be either a variable or hteral of type integer or real. 

All parameters must be present to be accepted by the Compiler. The disk which 
contains the file must be ordine upon execution of the statement, otherwise a run time 
error will be generated. 

BLOAD will load the file in the specified memory area. If Start_Address is zero, the 
file will be loaded to the address specified by the fiile information on disk, otherwise the 
file will be loaded to the address specified. If Bytes_to_Load is zero, the entire file will 
be loaded, otherwise only the specified number of b3rtes will be loaded. 

Example: (using an uncompressed picture file); 

BSAVE "PICTURE", 14753792, 32768 
BLOAD ''PICTURE'^ $E12000, $8000 

32,768 bytes of memory holding a Super High Resolution picture wiU be saved and 
then loaded with these commands. Note that the addresses in both lines are identical 
This example saves then loads the entire Super High Resolution screen 
(14753792-14786560 \ $E12000-$E19FFF) without any decompression. 

If your paint program can save the picture in binary format, you will be able to load 
this picture into memory with Micol Advanced BASIC using the following code: 

{Change to HGR2 for pictures drawn in 640 x 200 mode} 



Part Three: The Advanced BASIC Lan^age 



165 Chapter Thirteem Direct Memory Access 

PROGRAM Load_Picture_320 

HOME 

INPUT ''Enter full pathname of picture "; Picture? 

HGR 

BLOAD Pictures, $E12000, $8000 

GET A$ 

Picture files wiQ not load correctly if they were saved in a compressed format. 

BSAVE Svar, Start.Address, Bytes_to_Save 

BSAVE stands for Binaiy SAVE. Use BSAVE to save any information from memory 
into a binary file on disk. The file will be saved as type BIN ($06), 

Svar is the Pathname of the file, Svar may be either a string variable or a string 
literal. Start_Address is the address of the memory location whose memory image will 
be saved. Bytes_to_Save represents the size of the file in bytes. Start_Address and 
Bytes.lb.Save may be either of type integer or real in a variable or literal. 

All parameters must be present to be accepted by the Compiler. BSAVE will save 
the Bytes_to_5ave number of bytes from Start_Address. 

Example: (See BLOAD) 

Memory Management 

Micol Advanced BASIC has commands that allow you to allocate and deallocate 
memory as yoxir program requires. The memory may contain anything. Some memory 
may contain a graphics picture^ data for the program, etc. 

The User ED Number 

AQ memory within your Apple IIGS is managed by a Tool called the Memory 
Manager. When Micol Advanced BASIC is started up, the Memory Manager assigns an 
identification number to be used for all calls to it. This application ID number is active 
xmtil you quit Micol Advanced BASIC. 

This ID nximber is stored in memory locations 232 and 233 in the direct page and 
may be retrieved at any time using PEEK. 

GET_MEM (Handle&, Location&) 

This statement is used to request a block of memory from the Memory Manager. The 
memory may be used to allocate a Direct Page area or to allocate other memory for just 
about any purpose. Once allocated, you have exclusive use of this memory. 
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Haiidle& is a 4-byte memoiy location which will contain information necessary to 
firee the memory when you are finished with it. Location& is the actual address of the 
allocated memory block. Both parameters must be real variables. 

GET_MEM allocates a block of memory that is in a fixed memory bank with a fixed, 
page-aligned address that does not use Special memory (graphics memory, etc). The 
block is fixed, and locked. 

Before you can call GET_MEM, there are certain values you must establish: 

1. Memory location 202 (True_Value) indicates to GETJMEM where the memory 
will be allocated. A value of zero tells GET_MEM to get the block from 
anywhere in memory. Anon-zero value indicate that the block will be allocated 
firom a specific bank. 

2. The variable Location& must indicate firom which bank number the memory should 
be allocated- 

3. The value assigned to variable Handle& must indicate the amount of memory 
needed in bytes. 

After the call to GETJMEM is finished, the variable Handle& will contain the 
handle of the memory block allocated by the Memory Manager. The actual address of 
the block will be in Location&. 

If the memory is allocated successfully, True.Value (location 202) will contain a 
zero, otherwise True^Value will contain the error nxunber returned by the Memory 
Manager 

Handle& is required by FREEMEM to deallocate the memory block 

Example; 

POKE 202,1 {Get memory from a specific bank} 
Locations *• {Get memory from bank zero} 
Handle& = 256 {Get 256 bytes (one page)} 
GET_MEM (Handles, Locations) 
IF PEEK (-202) <> THEN BEGIN 

PRINT '^Error in memory allocation'" 
ELSE BEGIN 

PRINT '^The address of the block is: "/Locations 
END IF 



WARNING 



If a memory block is allocated directly by using the 
TOOLBOX command instead of GET.MEM, the block of 
memory must be deallocated using the proper Memory 
Manager calL 



» - 
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FREEMEM (Handle&) 

Tb deallocate a block of memory, use the FREEMEM command. The argimient is the 
handle of the block obtained with GET_MEM. Handle& must be a real variable. 

The memory may also be deallocated by letting the program finish. All memory will 
be released automatically 

Example: 

FREEMEM {Han<ile&) 

MOV_MEM Start^Addr, Niiin_of_Bytes AT Dest 

Tb move memory from one location to another, use the MOV^MEM command. The 
arguments may be either of type real or integer, 

Start_Addr is the address of the first byte that needs to be moved. Num_of_Bytes is 
the total number of bytes to be moved, and Dest is the address to where these bytes need 
to be moved. The maximum number of bytes that may be moved at one time is 65535 
bytes (one bank). The locations may not overlap, or the memory may copy over itself. 

One practical use of MOV_MEM is to save a part of the current text screen display, 
for example. MOV^MEM may be used to move 1024 bytes starting at 1024 to a safe 
location, and 1024 bytes starting at 66560 to another safe location. When returning the 
screen to its original display, move the memory back to the screen. 

Example: 

DIM Array% (1026) {Allocate a buffer} 

Array_Addr = ADDR (Array%{ ) + 3 

Screen^BankO = $400 

Screen_Bankl - $10400 

MOV_MEM Screen_BanlcO, 1024 AT Array_Addr 

MOV_MEM Screen_Bankl, 1024 AT Array_Addr 4- 1025 

HOME 

{To restore screen just saved} 

MOV_MEM Array_Addr, 1024 AT Screen_BankO 

MOV^MEM Array_Addr + 1025, 1024 AT Screen_Bankl 
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Chapter Fourteen 

Run Time Error Handling 
Overview 

Error handling, or error trapping as it is also called, is the art of dealing with 
iinexpected situations. These situations may be, for example, bad user input, an empty 
disk drive, improper data, or even an intentional user response which causes an error 
condition, such as pressing <Control>C> 

When an error occurs, control is usually passed to an error handling routine. An 
error handling routine, for example, may allow the user to recover from the error by 
giving precise instructions on how to correct the situation. After the error has been 
corrected, the program iisually resumes execution at a suitable point* 



IMPORTANT 



Do not confuse error trapping with debugging. Error 
handhng is a normal operation of almost every properly 
functioning program and is simply dealing with 
unexpected situations. Never use any of the commands 
described in this chapter until your program is properly 
debugged (unless, of course, you are debugging the error 
trap itself). 



Handling the Error 

During the program development phase, whenever an error condition arose, a 
message was displayed oh the screen describing the error and the line where the error 
occurred. You more than likely went to the Text Editor to fix the problem. This situation 
was carefully devised to help you debug your prograr ^ 

Now, you have gone beyond this phase so that your program operates as it should, or 
at least as dose as possible. Unfortunately, unforseen conditions may arise during the 
execution of the program and the system sending a message to the screen isn't adequate 
anymore. 

Now, the program error must be dealt with internally, and usually the program must 
continue on with its work. That is, the error must be handled. 

The Micol Advanced BASIC commands described in this section are all you should 
need to take care of these unexpected situations. However, this is a topic where 
creativity is required, so actually designing what happens in yo;ir error handling routine 
is largely up to you. 
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ONERR GOTO Module Jd 

If an error occurs during program execution, ONERK GOTO deactivates the normal 
debugging capability of Micol Advanced BASIC and transfers control to an error 
handling routine. ONERR GOTO also passes information to the program to help 
determine what the problem is and where it happened. 

When an error occurs during the execution of a program, the error number is placed 
into one of two memory locations location 154 or 155), 

Location 154 holds the error number returned by the run time routine. Location 155 
holds the error number returned by the operating system. Under no circumstance can 
both error conditions arise at the same time. The list of the error codes from the nm 
time routines is in Appendix C, The list of the error codes from the operating system is 
in Appendix D. 

Place the ONERR GOTO at a location prior to where you beheve the error is likely 
to happen; in practice, this is often at the beginning of the program. 

To deactivate an ONERR GOTO, place zeroes into the direct page locations 191 and 
192 using a POKE. This will enable the normal debugging capabiJity of Micol Advanced 
BASIC. 

It is often very useful to know on which sequential Kne niimber the error happened. 
The sequential line number where the error occurred is stored as a binary value in 
locations 204 and 205 in LSB, MSB order. The following program line will determine at 
which sequential line the error occurred: 

Line j:rror& = PEEK (204) + 256 * PEEK (205) 

It may be desirable to place the error handling routine as the last portion of code 
before the final END statement. This will help avoid confusion with the normal 
program code. 

Tb avoid an infinite error loop, you may want to deactivate the ONERR GOTO if 
execution errors should occur within the error handling routine. Don't forget to 
reactivate the ONERR GOTO by placing another ONERR GOTO as the last line of the 
error handling routine, if necessary. 

Example: 

PROGRAM Error_Example 

ONERR GOTO Error_Trap 

{<Prograin code>} 

END 

ROUTINE Error_Trap 

POKE 191,0 

POKE 192,0 {Turn off future ONERR GOTOs} 

IF PEEK (154) > THEN BEGIN 

PRINT "Language error # '';PEEK (154); 
ELSE BEGIN 

PRINT ^GS/OS error # ^'/PEEK (155); 
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END IF 

PillNT '" in line "; PEEK (204) + 256 * PEEK (205) 

END 

RESUME 

RESUME instructs the program to contiaue execution at the same liae or structured 
statement in which the error was encountered 

RESUME restores the previous FOR loop stack pointer as well as the stack pointer 
used for Procedures, Functions and Routines. If you intend to use a RESUME, then the 
error handling routine should contain neither FOR loops nor calls to subroutines 
(GOSUBs) as the values on the stack(s) may become corrupted* 

If RESUME is used in a program, the ERROR compiler option must be specified in 
the program. If ERROR is not specified, an error will occur at run time when 
RESUME is encountered. 

Example: 

PROGRAM Example 

@ ERROR {Required for RESUME} 

ONERR GOTO Error_Trap 

HOME 

Divisor = 

Dividend « 100 

Quotient ^ Dividend / Divisor 

PRINT "Quotient is: "/Quotient 

END {END needed to terminate program before error trap} 

ROUTINE Error_Trap 

HOME 

PRINT '^In Error Trap" 

Divisor = 10 {Stop another division by zero error} 

PRINT "^Press Return to resume program" 

GET Wait$ 

RESUME (Will execute the error line again) 
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Part Four: Creating the Apple IIGS Desktop 

Chapter One 

Desktop Programming 

Overview 

This chapter explains the Desktop metaphor created by Apple and shows what is 
needed in a Desktop program written under Micol Advanced BASIC - 

The Desktop Environment 

What is the Apple IIGS Desktop? The Desktop is a metaphor used by Apple to help 
individuals use computers without having to learn hard-to-remember and often 
diffiailt-to-use commands. This metaphor uses objects used in everyday life to 
conceptualize computer operations. 

It is not necessary to remember commands when a Desktop program is used; the 
operations appear on the screen in a manner the user is already famiUar with. The user 
only has to make a selection to perform the action. If you wish to learn more about the 
Desktop metaphor, get a copy of the Human Interface Guidelines from Apple Computer, 
Inc.. 

Desktop programming is somewhat difficult. It reqxaires a lot of planning and 
attention to details. A Desktop appUcation does a lot of little things ia the background 
that take Httle time to write into code. 

The Desktop commands used in Micol Advanced BASIC will control the vast m^ority 
of the functions needed by a Desktop program written by the average Micol Advanced 
BASIC programmer. 

Essentially^ there are three types of displays on the Apple IIGS Desktop: Menus, 
Windows and Dialog Boxes, We wiU explain what each of these is in detail in its 
respective chapter. For now, it is sufficient to know that they exist 

In general, information is passed to the appropriate Desktop command using two 
arrays: an integer array and a string array. The arrays must be large enough to hold the 
elements of the largest Dialog Box, Menu, or Window. The arrays are used to define the 
Dialog Boxes, Menus, and Windows but may be used for other purposes if memory is 
short. In addition, it is not necessary to have a different set of integer and string arrays 
for each Menu, Dialog Box or TOndow; they may be reused from call to call. 

The Desktop uses the Super High Resolution graphics screen, either in 320 mode or 
640 mode. Before any of the Desktop commands may be used, an HGR or HGR2 
co mman d must have been previously given to start the proper graphics mode. A TEXT 
command is used if you wish to erase the Desktop and return to normal text input. 

Define the Menus, Dialog Boxes and Windows by filling in the appropriate arrays 
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and use the appropriate Desktop command to display (and activate) the Menus, Dialog 
Boxes and Widows. 

The values returned by the movements of the Mouse and clicking in the Menu bar. 
Dialog Boxes, and Wxadows are caught in. a loop, called the Event loop, that handles all 
the commands and the choices the program's user makes while using the program- The 
actions performed by the \iser are often handled outside the loop ia a sub-section of the 
program, ACASE_OF statement does this job nicely. 

Desktop Commands 

Micol Advanced BASIC understands four commands to let you write applications 
that use the desktop. The MENU command controls the Menu bar. The WINDOW 
command directs how Windows open and dose. The DIALOG command manages all 
aspects of Dialog Boxes. The MOUSE command controls the actions performed by the 
program's user (the Event). 

A Desktop program must have the MOUSE command and at least one of the other 
three Desktop commands (DIALOG, MENU or WINDOW) to fimction properly; 
otherwise the program will not be able to respond to the user. 

Desktop capability under Micol Advanced BASIC is adequate for most of the 
applications written with Micol Advanced BASIC. The Tbolbox may also be called 
directly using the TOOLBOX command if you require a more advanced Desktop. 

Monitoring the Desktop 

MOUSE (Integer_Array ( ) 

The three types of Desktop displays: Menus, Windows, and Dialog Boxes, are all 
monitored by the MOUSE command. 

First, you have to create one of the Desktop displays using the MENU, WINDOW or 
DIALOG command. Once the display is as you wish, you must use MOUSE to allow the 
;iser to respond to the display. 

The only parameter required by MOUSE is an integer array dimensioned to at least 
20 elements. This array may have any value before MOUSE is executed, but will 
contain the value(s) needed to respond when control is returned to your program. 

You may have to place MOUSE in a looping situation, and access the values 
described in subsequent chapters. If you are accessing a Dialog Box, MOUSE need not 
be in any looping structure, as no response is returned xintil the user has responded to 
the Dialog Box. However, both MENU and WINDOW reqxiire MOUSE to be contained 
within a loop with repeated checks for the necessary values returned by the particular 
command. 

The individual aspects of the MOUSE command will be explained in more detail in 
the three chapters that follow. 
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Example: 

PROGRAM Desktop_Demo 

DIM EventRecord% (59) 

DIM DeskTopArray$ (42) 

{Dialog Boxes, Menus, and windows are defined here} 

{Program Start} 

HGR {Set 320 x 200 mode for DesJctop, required) 

GOSUB MenuBar {Define Menu Structure} 

GOSUB EventLoop {Handle the Users Actions} 

END {Des}ctop_Demo} 

{eof} 

The example programs on the disk /MAB. SUPPORT, ia the subdirectory 
Demo.Files/Desktop-Samples/ demonstrate the use of these commands. 



Prograimners, 



A Desktop application written in Micol Advanced BASIC 
uses the following tool sets: QuickDraw II, Event 
Manager, Window Manager, Control Manager, Menu 
Manager, tineEdit, Dialog Manager and Scrap Manager. 
These tools will be loaded and started automatically when 
one of the Desktop commands is executed by the program. 
They wiU be shut down when the Desktop is erased from 
the screen or the program fibcdshes execution. 
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Chapter Two 

Menus 
Overview 

This chapter describes the commands needed to create and monitor Menus, 

Menu Specifics 

Pxill-down Menus allow a user to make a single selection from a list of selections (a 
Menu list), among a set of lists (the Menu Bar), and perform a task based on this 
selectioiL 

Menu lists may be easily created, enabled (made selectable), disabled (made 
non-selectable), and removed. Each selection within a Menu List is called an Item, 
Items within a Menu List may be enabled, disabled, and removed just as easily. 

A distinction must be made between the Menu Bar, Menu Last, and Menu Item. A 
Menu Bar, the white rectangle that appears on the top of the Menu display, contains the 
Menu Lists. When a List in the Menu Bar is selected, a pull-down List of Items is 
displayed. The pull-down List is the entire collection of Menu Items for this Menu List. 
A Menu Item is a command. 

Defining a Menu 

The Menu Lists are defined in the reverse order in which they are displayed: the 
Menu List appearing on the right must be created first; the Menu appearing on the left 
must be defined last. This means, that the first defined Menu List (with the smallest 
element number) will be the right most Menu List displayed, and the last defined Menu 
List (with the highest element niimber) will be the left most appearing Menu List. 

The Items in a pull-down list should be listed with the most often used Item at the 
top and the least often used one at the bottom. 

Do not forget to define the Super High Resolution graphics screen with either an 
HGR (320 mode) or HGR2 (640 mode) before creating your Menus, 

Menu Definition Syntax 

{ [ MenuArray$ (Subscript) ='^> Menu List \ [Attr_Char ] N Menu_ID'l}" 
{ [ MenuArray$ (Subscript) = **nMenu Item\ [ Attr_Char ] N Menu.rDH} 
{ [ MetiuArray$ (Subscript) = "." ]} 
( [MenuArray$ (Subscript) = "^]} 

The definition of a Menu Bar is assigned to a string array which wiU be passed to the 
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command which actually makes the Menu. The Menu Lists and Items are assigned to 
the individual elements of the string array: One string array element holds one Menu 
List or Item definition. The string array must be dimensioned to a little more than the 
total nimiber of Items in the Menu definitioru 

Be sure to number the string array elements exactly. If the subscript number of the 
Menu array is repeated, the contents (Menu Item) of these elements wiU not be 
displayed 

A Menu List definition begins with any two title characters, which indicate the start 
of a Menu list, followed by the actu^ Menu List title between spaces. These List 
characters may be any visible characters, but the greater than S3mabol (>) is smtablej so 
we will use it exclusively in our examples. The Menu list Title is simply a text string 
which describes the list of Items to follow. Two spaces should appear before and after the 
Menu titles in 320 mode (HGR), and one space in 640 mode (HGR2); otherwise, the 
Menu List Titles wlU appear stuck one against the other when they are displayed- 

A Menu Item definition begins with any two item characters (diJGFerent fix>m those 
used in the list, we will xise a colon (:) in our examples) which indicates a Menu Item. 
Spaces before and after the Menu Items are not necessary: they will be done 
automatically. Following these two characters must appear the Menu Item Name, which 
is the text which will appear on the screen informing the user what the selection is. 

Following the Menu list Title or Menu Item Name is a backslash character (\) which 
indicates that the Menu List ED or Menu Item ID follows, followed, perhaps, by special 
attribute definitions. 

Menu Title and Item Identification Numbers 

A unique number must be assigned to each Menu List and Menu Item; otherwise, the 
program will not be able to determine which List or Item was chosen by the user Menu 
list and Item ID numbers should be listed in ascending order The identification 
numbers must be allocated as shown in Table 4.2.1. 

Table 4.2.1 ID Number AUocation Table 

Menu List ED * Description 

Internal use to indicate first Menu list 

1-255 Preferred ID numbers for Menu lists 

256-65534 May be used by user's application 

65535 Internal use to indicate last Menu 

If the Apple Menu is included, it must have an ED number of one (1). 
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Menu Item ID # 



1-249 

250-254 

250 

251 

252 

253 

254 

255 

256-65534 

65535 



Description 

Internal use to indicate first Menu Item 

Used by Desk Accessories 

Reserved for the Edit Menu Items 

Undo 

Cut 

Copy 

Paste 

Clear 

Reserved for Close command (in File Menu) 

Used by program's Menu Items 

Internal use to indicate last Menu Item, 



The Menu list ID or Menu Item ID is defined by using one of the unique numbers 
above preceded by one of the following letters: 

N - Number 

The letter N is followed by a unsigned decimal (ASCII) number. This number defines 
the unique Menu List ID or Menu Item ID in decimal. This characteristic will probably 
appear in every Menu List or Menu Item definition* 

H - Hexadecimal 



This letter is used to specify the Menu list ID or Menu Item ID as a hexadecimal 
value. You wiU probably wish to use N instead of H. 



Example: 

Menu$ CD 

Menu$ (2) 

Menu$ (3) 

Menu$ (4) 

Menu$ (5) 



» Title \N3" 
Item 1\N301" 
Item 2\N302" 
Item 3\N303" 



^ w 



{Menu title defined} 

{Menu item defined} 



{End of Menu list definition) 



{Other Menus would be defined here} 



Menu$ (99) = 



{End of Menu bar definition} 



Menu Attribute Characters 

These characters (-, *, B, C, D, I, 0, S, U, V, X) may be included with the Menu List 
ID or Menu Item ED and are used to give one or more specific features to a Menu list or 
Item such as: 
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Give a keyboard eqxoivaleat to a Menu Item 

Indicate a defaxalt setting to a Menu list or Item 

Separate Menu Items 

Give a specific style to a text Item 

Restore the colors of a Menu list or Item 

The attribute characters may be entered in upper or lowercase, by convention, 
uppercase characters are used. 

♦ - Keyboard Equivalent 

The asterisk tells MENU to display an Apple logo and a character to the right of the 
Menu Item to indicate that a keyboard equivalent is available. Menu lists may not have 
a keyboard equivalent. 

Some keyboard eqmvalents should be used for specific Menu Items (see Table 4,2.2). 

When using a letter as a key equivalent, be certain to define both an uppercase and 
lowercase character. When a special character (?, #, etc.) is used (especially where the 
Shift key must be pressed) as key equivalent, be s\ire to enter both characters in the 
definition; otherwise, the xiser may think that the key equivalent does not function 
properly. 

The key equivalent is automatically trapped by the MOUSE comjnand. 

Example 1: 

Menu$ (11) = '^: :New\*NnN259'' 

This definition allows you to use Apple-N (Apple-Shift-n) or Apple-n as key 
equivalents. 

Example 2: 

Menu$ (32) = ^^ : : Help . . . \V*?/N257" 

This definition allows you to use Apple-? (Apple-Shift-/) or Apple-/ (Apple-/) as key 
equivalents. 

Table 4.2.2 Reserved Keyboard Equivalents 



Apple Menu 


File 




Edit 




Help ? 


New 


N 


Undo 


Z 




Open 





Cut 


X 




Close 


w 


Copy 


c 




Save 


s 


Paste 


V 




Quit 


Q 







We strongly recommend you program some keyboard equivalents to offer an 
alternative to using the Mouse. Not everyone loves the Mouse. 
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Specifying Defaults 

Attribute characters C and D are used to show a specific setting at the creation of the 
Menu. Attribute C is used with Menu Items only. Attribute D may be used on Menu 
Lists and Items, 

D - Disable and Dim a Menu Title/Item 

The letter D prevents the user from employing a Menu List or Item until a specific 
event occurs; the name of the Menu Title or Item appears in grey. In the case of a Menu 
Liflt> the entire Menu List is deactivated. 

Use this attribute to disable a Menu List or Item in a Menu definition before 
displaying the Menu bar. To activate a disabled Menu Last or Item, use the appropriate 
Menu Control Number and MENU command described later in this chapter. 



NOTE 



Never disable the Apple Menu; otherwise, New Desk 
Accessories will not be available to the user. 



Example 1: 






{Water 


Menu is disabled} 


Menu$ 


(30) 


- ""» Water \DN3" 


Menu$ 


(31) 


= ": :Salt\N301" 


Menu$ 


(32) 


= '': :Fresh\VN302" 


Menu$ 


(33) 


- '^: :Poisonous\N303" 


Menu$ 


(34) 


_ n ff 


Menu$ 


(35) 


^ <Atf 


Example 2; 






{Items 


301 


and 303 are disabled} 


Menu? 


(30) 


- **» Water \N3" 


Menu$ 


(31) 


= ": :Salt\DN301" 


Menu$ 


(32) 


= '^: :Fresh\VN302" 


Menu$ 


(33) 


- '': :Poisonous\DN303" 


Menu? 


(34) 


^ w w 


Menu$ 


(35) 


^ XSff 



C - Item Selection Inilicator 

This attribute places the character following the C before the Menu Item Name. Use 
this character to indicate that a Menu Item has a default or current setting. 

The Check mark (character code 18) or the Diamond (character code 19) are the 
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usual characters indicating a default or current setting. 

Example 1: 

Menu$ (22} = '^::Hot Pepper\C" +CHRS (18) + '^N451" 

A check mark will appear in front of the word Hot Pepper. 

Separating Groui>s of Menu Items 

The attribute characters V and - (Dash) draw a line in a Menu List to separate 
groups of Items^ Use these characters to group Items that are independent of other sets, 
but related to the Menu under which they appear. They may not be used for Menu lists. 

V - Underline 



This letter 


is used to place an imderHne between two Menu Items 


Example: 








Menu? 


(21) 


- 


^» File \N2" 


Menu$ 


(22) 


= 


": :New\*NnN2001" 


Menu$ 


(23) 


- 


'*: :Open. . .\*OoN2002" 


Menu$ 


(24) 


' 


": ;Close\V*WwN255" 


Menu$ 


(25) 


- 


'^i :Save\*SsN2003" 


Menu$ 


(26) 


= 


'^: :Save As. . .\N2004" 


Menu? 


(27) 


= 


"::Revert to Saved\VN2005" 


MenuS 


(28) 


- 


'"::Print Setup. .. \N2006" 


Menu$ 


(29) 


- 


": : Print. , . \V*PpN2007" 


Menu$ 


(30) 


= 


": :Quit\*QqN2008" 


Menu$ 


(31) 


w* 





- (Dash) - Dividing Line 

This character provides a dividing line that makes more space between Items. The 
dash character must have its own Item Definition and Number The dividing line should 
always be displayed in grey (dimmed). This attribute separates Item Names with 
descenders to have a better looking Menu List. 



Example: 

MGnu$ 
Menu$ 
Menu$ 
Menu$ 
Menu$ 
Menu$ 



(06) 
(07) 
(08) 
(09) 
(10) 
(11) 



X ^^ 



^» Edit \D>I2" 
'^: :Undo\*Z2N250" 
'^ :-\DN9999" 
'": :Cut\*XxN251" 
Copy\*CcN252" 
Paste\*VvN253" 
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Menu$ (12) ^ '^ : : -\DN9999" 

Menu$ (13) = '^ : :Clear\N254" 

Menu$ (14) - ^^: :-\DN9999" 

Menu$ (15) - ^\ :Show Ciipboard\N260^' 

Menu$ (16) = "." {End of Menu List} 

Font Style Menu Item Characters 

The following attribute characters usually appear in the Font Style or Size Menu 
List. As with the INVERSE command, use these characters only to attract the attention 
of the user. 

The font used must be capable of representing the desired character style; otherwise, 
the text will appear in normal text. 

B - Boldface 

This letter makes the Menu Item appear in boldface characters. This attribute is 
often used in the Size Menu list to indicate that a true font size is available by 
displaying the point size in bold face. 

I - Italics 

This letter makes the Menu Item appear in italic characters. This style is available 
only when the QuickDraw 11 Auxiliary Tbol set is active. 

O ^ Outline 

This letter draws an outline of the Menu Item string. This style is available only 
when the QuickDraw II Auxiliary tool set is active. 

S - Shadow 

This letter adds a shadow to the name of the Menu Item. This style is available only 
when the QuickDraw II AuxUiary Tbol set is active. 

U - Underline 

This letter underlines the name of the Menu Item. 

The Shaston font, 8 points, (the current system font at the time of publication), does 
not support Underline, 

X - Restore Menu or Item Color(s) 

This attribute restores the color of a Menu Title or Item Name if it is displayed in a 
color other then black or white. The character X is used especially to restore the color of 
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the Apple logo; otherwise, the logo will turn green when the Apple Menu is selected- 
Example: 

MGnu$ (40) - ^»@\XN1" 

The color table for menus is set to the default colors (black and white). To alter the 
default colors^ use the TOOLBOX command* 

Apple Menu Items 

The About Program^Name Item 

This Menu Item must be the first item in the Apple Menu List. It is iised to display a 
Dialog Box containing the name of the program, version number, copyright information 
as well as any information the appHcation programmer wants to display The name of 
the program follows the word "About". 

Example: (see below) 



The Help... Item 

This optional Menu Item, if present, must be one of the top Items in the Apple Menu 
List. It is used to display a Dialog Box containing helpful information (hints, 
suggestions, etc) about the program being used 



(41) = 



Example: 

Menu$ (40) 
Menu$ 

Menu$ (42) 

Menu$ (43) 

Menu$ (44) 



^»@\XN1" 

:About Exajnplel\N257" 
:Help, , ,\*?/N258" 



— \\ // 



Example of a typical Menu definition: 

ROUTINE DefineMenuBar 

Array (0) = 1 {1 - Create Menus} 



Menu$ (01) =• 

Menu$ (02) - 

Menu$ (03) ^ 

Menu$ (04) - 

Menu$ (05) « 

MenD$ (06) = 

Menu$ (07) ^ 



'» Water \N3" 

': :Salt\N301" 

': :Fresh\VN302" {A dividing line will appear 
between Fresh and Poisonous} 

^ : :Poisonous\N303" 

'» Edit \DN2" 
': :ando\*ZzN250" 
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MenuS 


(08) 


= 


": :-\DN9999". 


Menu$ 


(09) 


- 


": :Cut\*XxN251" 


Menu$ 


[10) 


= 


**: :Copy\*CcN252" 


Menu$ 


:ii) 


= 


": :Paste\*VvN253" 


Menu$ 1 


:i2) 


- 


": :-\DN9999" 


Menu$ ( 


:i3) 


- 


'^::Clear\N254" 


Menu$ ( 


[14) 


- 


"::-\DN9999" 


Menu$ { 


[15) 


- 


"irShow Clipboard\N260'* 


Menu$ 


'16) 


- 


%v tr 


Menu$ ( 


:i7) 


= 


'"» File \DN2" 


Menu$ ( 


[18) 


- 


"" : : Open , . A *OoNxxx" 


Menu$ ( 


[19) 


= 


'^ : : Close \V*WwNxxx" 


Menu$ ( 


[20) 


= 


" : :Quit\*QqNxxx" 


Menu$ 1 


.21) 


- 


u y/ 


Menu$ ( 


'22) 


= 


"»@\XN1" 


Menu$ ( 


[23) 


- 


"::About Examplel\N257" 


Menu$ ( 


[24) 


= 


": :Help. . Av*?/N258" 


Menu$ < 


25) 


= 


V\ // 


Menu$ { 


26) 


= 


w// 


{End oi 


: Menu 


Bar definition} 



Defining the Menu 
MENU (EventRecord% ( ,DesktopArray$ ( ) 

The MENU command handles the Menu definition. Its required parameters are an 
integer array and a string array. The left parentheses of the array designators may not 
be left off the MENU definition, otherwise the Compiler will issue an error The string 
array was described above and must be set before this command is executed. 

Element zero of the integer array must contain the Menu Control Number which 
instructs MENU the command usage. Other integer array element uses will be defined 
below. 

Be certain the arrays are large enough to hold the entire Menu Definition; otherwise, 
an error will occur during execution. 

Example: 

{Define Menu Bar and its Menu Items} 
EventRecord% (0) = 1 {Menu Control Number, Create} 
{Menu defined in array DesktopArray$ } 
MENU (EventRecord% {, DesktopArray$ ( ) 
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How to Use the Menu Control Numhers 

The Menu Control Nximbers determine which actions will be performed by the 
MENU command. A Menu Control Number of one is used to create the Menu. The 
appearance of this Menu may be changed using other Menu Control Numbers. Menu 
lists and Items may be deactivated and reactivated or completely removed fix>m the 
Menu Bar, 

The actions are performed according to the following values passed to element of 

the integer array passed to MENU: 

Table 4^.3 Menu Control Numbers 

Code Action 

Remove a Menu List firom the Menu bar 

1 Create the Menu 

2 Reserved for Future Expansion 

3 Reserved for Future Expansion 

4 Enable a disabled Menu Item or List 

5 Disable a Menu Item 

6 Remove a Menu Item from a Menu list 

7 Add New Desk Accessories 

Remove a Menu List (0) 

Menu Control Number of zero closes the specified Menu List The Menu List wiU 
disappear from the screen, and be removed from memory. 



NOTE 



The entire Menu Bar must be recreated to display the 
removed Menu list again. 



To remove a Menu List, assign a zero to element zero of the integer array passed to 
MENU and pass the Menu Identification Number (assigned by you) of the Menu List to 
be removed to element one of the integer array. 

Example: <Program fragment> 

EventRecord% (0) - 

EventRecord% (1) - Menu_List_ID 

MENU (EventRecord% (, DesktopArray$ { ) 

Create the Menu (1) 

This Menu Control Number sets up and displays the Menu as it was defined in the 
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stiing array passed to MENU, 

lb create the Menu Bar and its Menu Lists, assign a one to element zero of the 
integer array. The string array defining the entire Menu must be assigned as described 
in the previous section. 

Example: 

{DeskTopArray§ previously defined} 
EventRecord% (0) - 1 {Create Menus} 
MENU (EventRecord% (, DesktopArray$ ( ) 

Reserved for Future Expansion (2) 

Reserved for Future Expansion (3) 

Enable a Disabled Menu List or Item (4) 

A Menu Control Number of four reactivates a disabled Menu List or Item thiat was 
disabled by Menu Control Number five. 

Tb reactivate a Menu List/Item, assign a four to element zero of tbe integer array^ 
and assign the number of the List/Item to be reactivated to element one of the integer 
array 

Example: <Program fragment> 

EventRecord% (0) « 4 

EventRecord% (1} = ItemNumber 

MENU (EventRecord% ( , DesktopArray$ ( ) 

Disable a Menu Title or Item (5) 

A Menu List or Item is disabled by using a Menu Control Number of five. The 
attribute character D is used only to disable a Menu Item when it is first displayed. 

To deactivate a Menu List or Item, assign a five to element zero of the integer array 
passed to MENU, and pass the List or Item ID to bp disabled to element one of this 
integer array 

Example: <Program fi:agment> 

EventRecord% (0) =5 

EventRecord% (1) = Menultem 

MENU (EventRecord% (, DesktopArray$ ( ) 

Remove a Menu Item from a Menu List (6) 

Menu Control Number of six removes a Menu Item from the specified Menu List. 
The Menu Bar must be recreated to display that Menu Item again. 

To remove a Menu Item, assign a six to element zero of the integer array passed to 
MENU, and assign the Item ID to be removed to element one of this integer array 
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Example: <Prograin fraginent> 

EventRecorci% (0) - 6 

EventRecord% (1) = Menultem 

MENU (EventRecord% (, DesktopArray$ { ) 

Add New Desk Accessories (7) 

If you have any New Desk Accessories within the DESK.ACCS folder on the boot 
volxime, the operating system will load these NDAs into memory at boot time. By using 
a Menu Control Ninnber of seven, you may cause all NDAs to be contained within the 

Menu list. 

The restrictions are that you must hav6 an Apple Menu (the Menu defined by @) and 
this Menu List must have a Menu ED of one. 

lb have these NDAs appear in your Menu List, assign a seven to element zero of the 
integer array passed to MENU and invoke the MENU command. That's all there is to 

it. 

Example: <Program j&:agment> 

Event Record% (0) - 7 
{Add Desk Accessories} 
MENU (EventReGord% ( , DesktopArray$ ( ) 

Unhighlight a Menu Title 

Each time a Menu Item has finished its task, the Menu List under which it appears 
may be returned to its original state to indicate that the operation is now finished. 

To unhighlight the Menu List of the selected Item, use Toolbox call 44 to the Menu 
Manager. Place this line at the end of the Event Loop. 

Example: <Program fi:^gment 

TOOLBOX (15,44: 0, MenuNuinber) {Unhighlight it} 

Monitoring the Menu 
MOUSE (IntegerArray ( ) 

It is not enough just to define a Menu; you must also monitor the user's response and 
take actions based upon this response. 

Tb monitor a Menu> you must make use of the MOUSE command The only 
parameter to MOUSE is an integer array dimensioned to at least 20 elements. This 
integer array may contain any values when MOUSE is executed, but MOUSE will 
return the values with which you may analyze the user*s response when control is 
returned to you. 

You must monitor the user^s response to the MENU command lErom within a loop 
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called the Event Loop. This Event Loop is best defined within a subroutine to facilitate 
changes and maintenance- 

When monitoring the Menu bar for a selection using the MOUSE command, look for 
a seventeen (17) returned in element zero of the integer array passed to MOUSE, 
Element zero of the passed integer array contains the Event code, and 17 is the Menu 
code. Once a 17 is received, immediately access elements 9 and 10 of the integer array 

Elements 9 and 10 of the passed integer array wiH contain the Menu Item ID 
number, and the Menu List ID number respectively These values are needed to 
determine which Menu Item has been chosen. Elements 1 through 10 of this integer 
array wiU contain the Task Record which contains additional information about the 
user's response (see table 4,2.4), 

Once a response is received, the program must direct the execution to a module that 
will handle the action indicated by the Menu Item, For example, if Quit is selected, the 
program shoiild exit the Event Loop and invoke the ShutDown routine. 

Example: 

{Menus previously defined} 
Quit! = FALSE 

WHILE NOT Quit! {Top of Event Loop} 
MenuID = 
MOUSE (Array% ( ) 
TaskValue =- Array% (0) 

IF TaskValue - 17 THEN BEGIN {a Menu was chosen} 
MenuID = Array% (9) {Menu Item} 
MenuTitle = Array% (10) {Menu Number} 
{Direct execution to proper module} 
CASE_OF MenuID 

DO 261 {New} 

GOSUB NewGame {Open a Window} 
ENDDO 
DO 262 {Quit} 

Quit! = TRUE {Quit prograin} 
ENDDO 
ELSE_DO 

BELL {Error condition} 
BELL 
ENDCASE {MenuID} 

TOOLBOX (15,44: {False}, MenuList) {Unhighlight it} 
END IF 
WEND {Event Loop} 
{...ShutDown Code,..} 
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<Prograin continues> 

Table 4.2.4. Menu Codes Returned by MOUSE 
Event Code Element Ninnber Description 

Task value 

17 = Mouse on Menu Item 

1 What field of Task Record 

1 ~ Mouse Down Event 

2 & 3 Message field of Task Record 
4 & 5 When field of Task Record 

6 & 7 Where field of Task Record 

(Mouse location) 
8 Modifiers field of Task record 

9&10 l^skData 

For more information on defining standard Menu applications, refer to Apple's 
Human Interface Guidelines: The Apple Desktop Interface, 

The MENU program in the Desktop, Samples/ folder on the MAB.SUPPORT disk 
demonstrates how to use the Menu Control Numbers. 
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Chapter Three 

Windows 

Overview 

This chapter shows how to do Windows and provides guideliaes on how to create, 
manage and draw in Windows, Tb use special Windows, consult the Apple IIGS Toolbox 
Reference Manuals or some other comprehensive documentation of the Apple IIGS 

Toolbox* 

Examples of the techniques described in this chapter are Included in the program 
WINDOW in the Desktop. Samples folder of the MAB.SUPPORT Disk. Please refer to 
the WINDOW program as you study this chapter. 

What are Windows 

A Window is a structure in which information, such as a docimient or a picture, is 

presented to the user by the application program. Any text or graphics image that may 
be drawn with the Super High Resolution commands may be presented in a Wndow. 

A Window consists of a frame that surrounds the image and a content area inside the 
frame in which the image is presented. Although a Window firame may be any size or 
shape, two standard styles of Window frames are supported: the document Window 
frame and the alert Window frame. 

The document-style frame supports optional controls that may be used to change the 
size of the Window and the position of the document within the Window. The alert frame 
is mainly used to create alert dialogs. This style of frame, however, may also be used for 
a Window. 

The controls in a document frame are optional, and may be used in any combination. 
They include the title bar, close box, zoom box, vertical scroll bar, horizontal scroll bar, 
size box and information bar. 

Managing Windows 
WINDOW (Integer^Array (, String_Array$ ( ) 

The WINDOW command supports the creation and closure of Windows, and provides 
a method to convert Window pointers to "VWndow nuxobers and vice versa* 

WINDOW requires two parameters; an integer array and a string array These 
arrays will contain the information required to create and/or modify the Window. Be 
certain these arrays are dimensioned large enough to contain all the information 
required by this command. 

Element of the integer array holds the Window Control Number that specifies 
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which function is to be performed by the WINDOW command in accordance with the 
following table: 



Table 4.3.1 Window Control Numbers 
Action 



Code 



1-10 
11 
12 

Creating the Window 



Close an application Window 

Create the specified ^^ndow 

Find the pointer of a specific Window 

Fiad the Window number of a specific pointer 



lb create a Window, assign the values from the table below to the integer array 
passed to the WINDOW command. 



Programjners 



The variable names from the Tbolbox manual are 
included in the table below to aid in identifying the 
associated NewWndow parameters in the Tbolbox 
manual. 



Table 4,3*2 Create Window Parameters 
Element Variable Value 




1 

2 

3 



Window Number to Create (1 - 10) 
wFratneBits 

Framebits. See Table 4,3.3. 

wTitle 

String array element of Window title. 

wDataH 

Height of Window data area- Used to compute the right scroll bar. 

Set to if the Window has no right scroll bar, 

wDataW 

Width of Window data area. Used to compute the bottom scroll bar. 

Set to if the Wrudow has no bottom scroll bar, 

wMaxH 

Max content height allowed when using the size box< If set to 0, will 
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Element Variable Value 

defaxilt to take up the height of the desktop. Set to if the Window has 
no size box. 

6 wMaxW 

Max content width allowed when using the size box. If set to 0, will 
default to take up the width of the Desktop. Set to zero if the Window 
has no size box, 

7 wScrolIVer 

Number of pixels to scroll the content region when the up or down 
arrows are selected in the right scroll bar. Set to if the Window 
has no right scroU bar, 

8 wScrollHor 

Number of pixels to scroll the content region when the right or left 
arrows are selected in the bottom scroll bar. Set to if the W^dow 
has no bottom scroU bar. 

9 wPageVer 

Number of pixels to scroll the content region when the up or down 
page regions are selected ui the right scroll bar. Set to if the Window 
has no right scroU bar. 

10 wPageHor 

Nimiber of pixels to scroll the content region when the right or left 
page regions are selected in the bottom scroll bar. Set to if the Window 
has no bottom scroll bar. 
11-14 wPosition 

Rectangle data structure that uses elements 11 through 14 of the array 
to define the initial position of the Window on the screen, 

11 Y ftiiTtiTniim value 
Tbp edge of Window, 

12 Y mflYiTniiTiri value 
Bottom edge of TOndow. 

13 X minimum value 
Left edge of Window, 

14 X maximum value 
Right edge of W^dow, 
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Progranuners 



All other NewWindow parameters are set to default 
values when WINDOW makes the NewWindow call to 
create the Window. This should be satisfactory for most 
Windows. If other values are needed, then you must 
either use Ibol calls to change the desired values after the 
Window has been created, or you must call NewWindow 
directly. The latter requires much more manipulation of 
data structures and precludes using the Micol Advanced 
BASIC WINDOW command. 



If the Window has a title bar, pass the Window title string in the appropriate element 
of the string array, as specified in element 2 of the integer array. 

Creating The Window 

Assign a ^^i^dow number into element 1 of the integer array The W^dow number is 
an arbitrary identifier for the window in the application program. VaKd Window 
nxmabers are in the range 1 - 10. This means that a Micol Advanced BASIC Desktop 
program may have a maximum of 10 TOndows open at one time. The Window nxnnber is 
used by the Close function of the WINDOW command to determine which ^^^dow to 
close. 



Programmers 



When creating a Window, the WINDOW command will 
return a pointer (address) to the Window's Grafport, This 
pointer is a four-byte long integer. The low word of the 
pointer will be returned in element 0, and the high word 
in element 1 of the integer array This pointer may be 
needed to make calls to the Window Manager. The 
pointers may either be saved in temporary variables as 
each Window is created, or a W^dow Control Number 
may be used to look up the pointers whenever they are 
needed. The use of the WINDOW command to look up 
pointers to open Widows is discussed later in this 
chapter. 



Setting Wframebits 

This section is a description of wFrameBits (described in Table 4.3.2); the value 
assigned to element one of the integer array passed to the WINDOW command. 

WFrameBits is a bitflag (a binary number that is treated by Micol Advanced BASIC 
as an integer value) that determines the type of Wndow frame and which optional 
controls will be available to the application Window. It also specifies other optional 
behaviors of the Window frame. 
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Tb calculate the integer value of wFrameBits, start with zero, then add the values 
from the table below to select the features that you want. If you specify a value of for 
wFrameBits, the will be replaced with a default value that will create a Mndow with 
all of the standard TOndow features. 



Table 4.3^ Window FrameBits 



Bit 


1 



Label 



fCtlTie 



Value 



fHilited 


DS 


doomed 


2 


fAUocated 


DS 



DS 



4 


finfo 


16 


5 


fVifl 


32 


6 


fQContent 


DS 


7 


fMove 


128 


8 


fZoom 


256 


9 


fFlex 


512 


10 


fGrow 


1024 


11 


fB Scroll 


2048 


12 


fRScroU 


4096 


13 


CAlert 


8192 


14 


fClose 


16384 


15 


fiitle 


32768 



Feature On (1) / Off (0) 

HighHghted / Not Highlited 
Display Size: 
Zoomed / Not zoomed 
Window Record: 
Allocated /Not Allocated 
Window Controls: 
Inactive / Active 
Info bar / No Info bar 
Visible / Invisible 
Mouse Activates Window 
Movable / Non-movable 
Zoom Box / No Zoom box 
Maintain origin / Change origin 
Grow Box / No Grow box 
Horizontal Scroll Bar / No bar 
Vertical Scroll Bar / No bar 
Window Frame: 
Document / Alert 
Close box / No Close box 
Title bar /No Title bar 



DS = Default Setting. The values you set are ignored 

Bit fHiUted 

Used internally. The value you set does not matter 

Bit 1 fZoomed (value = 2) 

Zooms the Window to the size of the entire Desktop when this bit is set to 1, 
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Bit 2 CAllocated 

Used internally to firee the memory area used by a Window. The value you set does 
not matter. 

BitSfCtrlTie 

Used internally. The value you set does not matter. 

Bit 4 finfo (WARNING: Set to zero) 

This bit is used to add an information bar to the Window. Info bars may be 
supported only by an assembly language routine linked in* If this bit is set to 1, the 

program will crash. 

Bit 5 fVis (value = 32) 

This bit determines if the Window is visible when it is created. If this bit is cleared^ 
the Window will be invisible when created. If this bit is set, the Window will be visible. 



Programmers 



After creation, Windows may be made visible or invisible 
Xising the ShowWindow and HideWindow Tool calls. 
According to the Toolbox documentation, this bit is used 
internally by the Window Manager and the value you set 
does not matter. However, contrary to Apple's Toolbox 
documentation, for System v5-04 (GS/OS v3.3) and 
earlier, we have foujad this information to be incorrect. 



Bit 6 fQContent (value = 64) 

Used internally The value you set does not matter. 

Bit 7 fMove (value = 128) 

Permits the Window to be dragged by the title bar when this bit is set to 1. 

Bit 8 ffioom (value = 256) 

The title bar will have a zoom box when this bit is set to 1. 

Bit 9 fFlex (value = 512) 

If this bit is set to 1, the data height and width are flexible. 
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Bit 10 fGrow (value = 1024) 

The Window will have a grow box (size box) if this bit is set to 1. 

Bit 11 fBScroU (value = 2048) 

The Wiadow wiJl have a horizontal scroll bar if this bit is set to 1. 

Bit 12 fElScroU (value == 4096) 

The ^todow will have a vertical scroll bar if this bit is set to 1. 

Bit 13 fAlert (value = 8192) 

The Wiadow will have an alert frame if this bit is set to 1. In this case, set the 
foUowing bits to 0: 8, 9, 10, 11, 12, 14 and 15. 

Bit 14 fClose (value = 16384) 

The Window will have a close box if this bit is set to 1. 

Bit 15 fKtle (value = 32768) 

The Window will have a title bar if this bit is set to 1. 

If the Window has either scroll bars, it should also have a grow box and a zoom box 
(bits 8, 10 with either 11 or 12). 

Closing a Window 

Call the WINDOW command with the following values in the integer array to close a 
\Wndow: 

Element Value 



1 Window Number 1 - 10 

This command will remove the appropriate Window firom the Desktop and will free 
all memory used for the Window's data structures. To reopen the Window, your 
appHcation must again execute the code to create the Window. 

Example: <Program fragment> 

{Close a Window} 
EventRecord% (0) =0 
EventRecord% (1) - WindowNumber% 
WINDOW (EventRecord%(, DeskTopArray$ ( ) 
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Using A Specific Window 

Before anythiag may be done in a Window, either draw in a Window or call an update 
routine, one of two methods may be nsed to have access to a TOndow: 

1. Use the Window Control Number (1-10) assigned by you to the W^dow during this 
creation 

2. Use the pointer of the Window assigned by Micol Advanced BASIC to the T\^dow 
during its creation. Most Window Manager Tbol functions need the WindoVs 
poiater to do its task 

Obtaining the Pointer of a Window 

The pointer is returned in elements and 1 of the integer array when the Window is 
created by the WINDOW command. The pointer may be saved in variables as the 
Windows are created or the WINDOW command may be used to look them up whenever 
they are needed. 

The WINDOW command will return the pointer to any of the ten \Wndows that may 
be created using the WINDOW command. If the pointer to a Window number that is not 
currently open is requested^ zeros will be returned- 

Element Value 

11 

1 Window number (1-10) 

2 pointer retiuned (low word) 

3 pointer returned (high word) 

Example: <Program ft^gment 

{Get the Window's pointer} 

EventRecord% (0) = 11 

Event Record% (1) = WindowN\iinber% 

WINDOW (EventRecord% (, DeskTopArr? $( } 

{Low part of the pointer} 
WinPtrL% = EventRecord% (2) 

{High part of the pointer} 
WinPtrH% = EventRecord% (3) 

Obtaining the Number of a Window 

The WINDOW command may also be used to determiae which Window number a 
pointer belongs to. For example, if it is detected that the user clicked ia a Window's close 
box, a pointer to the Window to be closed will be returned in the integer array used by 
the MOUSE command The application may then use the WINDOW command to 
determine which Window number the pointer belongs to, then use the WINDOW 
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command again to close the Window with that Window number. 
Element Value 

12 

1 Window number (1 - 10 returned) 

2 Pointer (low word) 

3 Pointer (high word) 

Example: <Program fragment> 

{Get the Windows pointer} 

EventRecord% (0) =-12 

EventRecord% (2) ^ WinPtrL% {Low part of the pointer} 

EventRecord% (3) - WinPtra% {Bigh part of the pointer} 

WINDOW (EventRecord% { , Des}cTopArray$ ( ) 

WindowNiimber% = EventRecord% (1) 



Programmers 



The WINDOW command is designed to be a general use 
command in creating the Apple IIGS Desktop. It is 
suitable for the vast majority of uses. However, Advanced 
programmers should know that internally, WINDOW 
uses the Window Manager Tbol to create and manage 
Windows. If you wish to create more elaborate Windows, 
you may use the TOOLBOX command to the Window 
Manager to do this. 



Monitoring Windo\s;^s 
MOUSE (Integer_Array ( ) 

After a Window has been created, it is necessary for the appKcation program to 
monitor and respond to certain events that affect the Window, and to maintain the image 
in the Window's content area- 
Monitoring events in Windows is handled by the MOUSE command. 

The following actions are done automatically by the MOUSE command when a 
\Wndow is being monitored: 

Activating an inactive Window to bring it to the top (assuming more that one 
Window is open) and making it active. A click of the Mouse on any region of a 
Window activates it. 

Dragging the active Window by holding the Mouse button down while the cursor 
is on the Title Bar. 

Changing the size of the active Window when the user clicks in the Zoom Box, 
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Changing the size of the active Window to resize it by holding and dragging the 
Size Box- 

The following actions are partially automated by the MOUSE command: 

Closing the active Window when the user cHcks in its Close Box. The appHcation 
program will be notified when a close box has been clicked, and will return a 
pointer to identify which Window's close box was clicked. The application 
program must actually close the Window, 
* Redrawing the Window^s contents when a hidden portion of the content region is 
exposed. Hidden portions are exposed when Windows are first opened, when the 
size or zoom boxes are used, or when Windows are dragged around the desktop 
exposing previously covered or oflf-screen areas of Windows* 

Window Watching Information 

Only one event at a time may be reported. As events occur, they are stored in 
chronological order in an Event Queue, and are reported and cleared firom the queue, one 
at a time, each time MOUSE is called* The application program uses the MOUSE 
command inside a loop called an Event Loop. This loop removes events firom the event 
queue one at a time, and calls the Micol Advanced BASIC routines to respond to each 
event. This is the heart of Desktop programming on the IIGS, 

When an event is detected in a Window, element zero of the integer array referenced 
in the MOUSE command will return the Event number, which will tell you what action 
was taken by the user Elements 1 through 10 will contain the T^k Record which will 
provide additional information about the event. 

The following values returned in element indicate events that affect a Window, and 
its pointer. The values affecting the Window appear in elements 9 and 10 of the integer 
array passed to MOUSE: 

Value Description 

No event to report 

6 Update event, Oneof the Widows needs its contents redrawn. 

1^ Mouse down in Content Region, 

22 Mouse down in GoAway box (close box), 

24 Mouse down in Info Bar. (not used by Micol Advanced BASIC). 

27 Mouse down in W^dow frame (but not in scroll bar) 

The following events are handled internally by the system. The appHcation program 
need take no action in response to these events: 
Value Description 

No event 

8 Activate/Deactivate Window 

19 Mouse down in Content Region. MOUSE will select (highlight) 

the Wndow, 
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20 
21 
23 



Mouse down in Title Ban MOUSE will select the Window and 

handle dragging. 

Mouse down in Size Box. MOUSE will select the Window and track 

the grow \Wndow control if used. 

Mouse down in Zoom Box, MOUSE will select the Window and track 

the zoom control 



Handling Window Updates 



NOTE 



This section is intended mainly for advanced 
programmers; ignore the areas you cannot understand* 
Please note that Task Master is an internal routine 
within the Toolbox that automatically performs updates 
upon a Window whenever the user references this 
Window. Few of you will need to worry about this aspect 
of doing Windows- 



Whenever a previously hidden portion of a Window's content area becomes exposed, 
the Window needs to be updated (needs to have its image redrawn). This occurs when a 
Wndow is first opened, when a Window is zoomed, when a WndoVs size box is used> 
when a portion of a \Wndowis dragged firom an off-screen to on-screen position, or when 
one Window is moved, exposing a portion of another Window that was underneath. 
Whenever a \Wndow needs to be updated, an Update Event (6) is generated. 

Two methods are provided for handling update events. If the application program 
has an assembly language routine that draws the Window's contents, the address of this 
routine may be passed in the field wContDefProc in the NewWindow tool caU. In this 
case, TaskMaster will call the application's assembly language routine whenever it needs 
to update the Window. This method completely automates Wndow updates. 



NOTE 



Micol Advanced BASIC^ run time routines cannot be 
called from inside a program, so this method is not 
possible without a linked-in assembly language routine. 
Such a routine is available commercially through the 
MaBug Users Group. 



As an alternative method for handling updates, an update event is reported 
whenever a Window needs to be redrawn. This method is used whenever the application 
has not passed the address of a machine language update handler Most Micol Advanced 
BASIC programs will use this method. 

An update event is reported by returning a six (6) in element of the integer array 
used by the MOUSE command. The pointer to the Window needing updating is 
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returned in Elements 9 and 10 of the integer array. Element 9 contains the low value of 
the pointer and element 10 contains the high value. 

The application program must determine which Window needs to be updated, then 
call the appropriate DrawContent routine that is spedfic for that Window. (A 
DrawGontent routine draws the contents of a specific Window.) The ntxmber of the 
Window that needs to be updated (with a 12 in element 0) to convert the Window pointer 
returned by the MOUSE command to the corresponding Window number. 

The appHcation should include a DrawContent Procedure for each Window. A 
DrawContent Procedxire draws the entire current image of the Window's contents using 
Super High Resolution commands. The appUcations event loop should call the 
appropriate DrawContent Procedure in response to an update event for an application 
Window 

The DrawContent routine has a different structure for Windows with and without 
scroll bars. Both forms are illustrated in the WINDOW program on the MAB.SUPPORT 
disk. 

For Windows without scroU bars, the DrawContent procedure shovdd perform the 
following actions: 

• Call GetPort (tool call $1C04) to save the current GrafPort into temporary 
variables. 

• Call SetPort ($1B04) to make the Window's GrafPort the current GrafPort, 

• Call BeginUpdate ($1E0E), This informs TaskMaster that you are handUng the 
update event. TaskMaster will continue to report an update event until you 
inform it, through calls to BeginUpdate and EndUpdate, that the update event is 
being handled Only then will TaskMaster report the next event in the Event 
Queue- 
Draw the image using Super High Resolution commands, 

• CaU EndUpdate ($1F0E) to inforai TaskMaster that the update has been 
completed. 

• Call SetPort ($1B04), passing the GrafPort pointer saved firom the GetPort call 
above, to restore the current GrafPort- 

For Windows with scroU bars, the procedxnre is sHghtly more complex. It should 
perform the following actions: 

• Call GetPort ($1C04) to save the ciirrent GrafPort. 

• Call StartDrawing ($4D0E). This makes the Window's GrafPort the current 
GrafPort and adjusts the Window's origin, and therefore the position in which 
the image will be drawn in the Window, to correspond to the current setting of 
the scroll bars. 

CaU BeginUpdate ($1E0E). 

Draw the image using Super High Resolution commands. 

Call EndUpdate ($1F0E) 

Call SetOrigin ($2304) to restore the Window's origin. 

Call SetPort ($1B04) to restore the current GrafPort. 

When a W^dow is created, an update event is generated immediately after the 
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WiQdow frame is displayed. For this reason, an application does not need to provide 
code specifically to draw the initial image in the Window* An update event will occur 
when the Window is created. The appUcations event loop will then call the appropriate 
DrawContent routine to update the ^ndow thus creating the initial image. 

If you ever wish to change the image in a Window, the appHcation may simply 
redraw the image. The application should call GetPort to save the current GrafPort, call 
SetPort to make the window's GrafPort the current GrafPort, draw in the Window, then 
call SetPort to restore the old GrafPort 

If a Window's image changes during the course of the program, that Window's 
DrawContent Routine must contain conditional logic to insure that the current image 
will always be drawn in response to update events. If a DrawContent Routine is not 
coded properly, the Window could be refreshed with an out-of-date image in response to 
an update event 

The sample program WINDOW includes a simple example of a Window whose image 
can change. W^dow number 3 contains either a happy face or a sad face depending 
upon which Menu Item has been selected by the user. The Menu handler sets the global 
boolean variable gHappy! to TRUE if the current image is the happy face or FALSE if 
the current image is the sad face. The DrawContent Routine checks this variable to 
determine which face to draw, happy or sad, in response to update events. In this way, 
the application always responds to update events in this Window by drawing the correct 
(current) image. Your applications must also guarantee that all DrawContent Routines 
always draw current images. 

Drawing in a Window 

Any vaHd Super High Resolution command may be used to draw inside a Window; 
this includes the DRAWSTR, HPLOT, and HPLOT TO commands, and Tbolbox calls. 

It is often necessary to know the exact size of a string, in pixels* Use the LEN (string 
length) function. LEN will store the size, in pixels, in True_Value (locations 202 and 
203) when the Super High Resolution screen is active (HGR or HGR2). 

To draw in a Window, the current GrafPort must be changd to the Window's GrafPort 
you want to draw into. A GrafPort is a data structure that completely describes a Super 
High Resolution drawing environment Each time a ,*^ndow is created usiag the 
WINDOW comuaaand, a GrafPort also is. The pointer returned by the WINDOW 
command is the pointer to the Window's GrafPort. 

The correct procedure for changing GrafPorts is as foUows: 

• Call GetPort ($1C04) to get a pointer to the current GrafPort, The current 
GrafPort is the GrafPort that is currentiy open — the one in which the Super 
High Resolution is currently active. 

Save the pointer to the current GrafPort in temporary variables. 

• Call SetPort ($1B04) to make the Window's GrafPort the current GrafPort. 
Execute the Super High Resolution commands to draw in the Window. 
CaU SetPort to restore the previous GrafPort, 
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The reason the current GrafPort must be saved and restored is to assure that things 
are left as they were. If you fail to follow this practice, problems such as having Desk 
Accessories draw in your Windows because the Desk Accessories become confused about 
what is the current GrafPort will arise. Remember, leave things as you find them and 
you will have no problems. 

Note to Advanced Programmers 

The rectangle in elements 11 - 14 of the integer array referenced in the WINDOW 
command, when the Wndow is created, is passed to both wPosition and wZoom for the 
library's call to NewWindow. This design simplifies Windows for beginners, since these 
parameters need not be different for most Windows. Several other fields in the Window 
parameter list are also set to default values, for example, wRefCon and wContDefProc 
are set to zero. The default values may of course be changed using Window Manager 
Tbol calls- 
Advanced programmers m^ wish to call New Window directly. In this case, aU of the 
parameters in the New^V\^dow parameter Hst may conveniently be passed in an integer 
array. When calling NewWindow directly, ytju may not use the WINDOW command to 
dose the Window or to convert between pointers and Window numbers. 

wInfoDefEVoc is also set to the default value zero by the WINDOW command when 
creating a Window. This is necessary because Mieol Advanced BASIC cannot provide a 
machine language information bar drawing routine for TaskMaster to call. Accordingly, 
Micol Advanced BASIC does not support Window info bare unless the application 
provides a linked-in assembly language routine to draw the info bar. 
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Chapter Four 

Dialog Boxes 
Overview 

This chapter shows how to create and monitor Dialog Boxes within your Micol 
Advanced BASIC programs. 

Dialog Box: Definition 

A Dialog Box is like the front of a television or stereo set: it is a panel with control 
dials and buttons, etc. Just like a television, these dials and buttons are used for control. 

A modeless Dialog Box is a panel that allows the xiser to do other things while the 
Dialog Box is still on the screen; for example, the tool of a paint/draw program or the 
Find/Replace box of a word processor or a data base program. 

A modal Dialog Box is a rectangle that forces the user to act on it before doing 
anything else like an "About.,,'* box. Micol Advanced BASIC may be used to create 
modal Dialog Boxes. If you wish to create modeless Dialog Boxes, you will have to make 
use of the TOOLBOX command. 

Dialog Boxes, by convention, are centered on the display and do not cover the entire 
screen. They may contain graphics, descriptive or informative text, fill-in areas, and 
control-like buttons. 

The point of origin for the Dialog Box is the upper left comer of the Desktop, position 
0,0. Make sure not to exceed the maximum X coordinate on the horizontal axis 
depending on the graphics mode (320 or 640), otherwise the right part of the Dialog Box 
will be hidden from view. 

lb be meaningful, a Dialog Box must contain Parts to which the user may respond. 
Parts may be added, disabled, enabled, etc, as the need arises. 

Do 1 A forget to define the Super High Resolution graphics screen with either an 
HGR (320 mode) or HGR2 (640 mode) before creating your Dialog Boxes. 

Controls and Labels 

The purpose of a Dialog Box is to give the user an easy, and straightforward way to 
communicate with the program. This is usually done with a symbol used in everyday 
life, such as a radio button, with a simple descriptor, that the user can easily relate to. 
This symbol, together with its descriptor, is what we will call a Dialog Box Part. 

Each Part in a Dialog Box has 6 components: 

1. The Part ED Number. Each Part must have a distinct ED number The ID 
number may range firom 1 to 255, An ID number of is invalid and will cause a 
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run tune error iii i 

2. The Part Location. All Parts use coordinates relative to the upper left comer of 
the Dialog Box. These coordinates, expressed in pixels, are called local 
coordinates. The upper left comer of the EHalog Box is local coK)rdinate 0,0. If 
the coordinates specified for the Part are greater than the maximum boundaries 
of the Dialog Box, the Part will be invisible* No error is generated, 

3. The Part Type. Five diEFerent types of controls and one type of label inay be 
displayed using Micol Advanced BASIC, 

4. The Characteristics of the Part. The characteristic value (also called PartFlag) 
of a Part depends on the type of the Part used. Not all Part types use this 
component: see the specific Part for details- 

5. The Value of the Part, This variable holds the value the Part has when it is first 
displayed. The Part Value depends on the type of the Part used- Not all Part 
types use this component: see the specific Part for details- 

6. The Part Descriptor, Most Parts must be labeled with words describing, as 
closely as possible, the action to be performed Not all Part types use this 
component. See the specific Part for details. 

Table 4.4.1 Standard Dialog Part Types 
Type Value Part Type 

10 Push Button 

11 Check Box 

12 Radio Button 

13 Scroll Bar 

15 Static Line 

17 Edit Line 

The Push Button 

The push button produces an immediate or continuous action when it is pressed. It 
has round or square comers with a single or a bold outliae. Its Part type is ten. 

A push button with an ID of one will have a bold outHne. All other push buttons with 
ED numbers fix>m two to 255 will have a simple outline. 

The button item with an ID of one is the default button, A default button should not 
be used to control a destructive command. If a default button is not needed on a Dialog 
Box, do not use ID number one for a push button. 

The Eetum key is the keyboard equivalent of a button with ID one (usually *^0K") 

and the Esc key is the keyboard equivalent of a button with ID two (usually "Cancer). If 
a button does not have an ID of one or two, the keyboard equivalents wiU be 
non-functional. 

The display rectangle of the button will be calculated automatically by supplying the 
upper-left coordinates (WBn Y, Min X, relative to the Dialog Box) of the Part, and setting 
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the lower-right coordinates to 0,0. 

The PartValue is unused (set to zero) with push buttons. 
The itemFlag defines the shape of the button: 

Round comers, single outline 

256 Round comers, bold outline 

512 Square comers, single outUne 

768 Square comers, single outline with shadow 

The Check Box 

A check box is a box that may be filled with an X (ON) or be left empty (OFF). It is 
often used to select options that will cause changes later on. The action of a check box is 
independent of other check boxes on the same Dialog Box. Its Part Type is 11* 

The display rectangle of the check box will be calculated automatically by supplying 
the upper-left coordinates (Min Y, Mhx X, relative to the Dialog Box) of the Part, and 
setting the lower-right coordinates to 0,0. 

The label is placed on the right side of the check box. Its description should be as 
long as necessary, but it may not exceed one hue. 

The PartValue has the initial setting of the button (0 = OFF, 1 = ON). 

The PartFlag is not used (set to 0) with check boxes. 

The Radio Button 

A radio button simulates a button like the one in a car radio. The button is filled 
with a drcle to indicate the ON setting or empty to indicate it is OFR 

A Radio Button is used to select only one option that will cause a change later on. 
The selected button will turn ofi" the button previously selected on the Ehalog Box. A 
Dialog Box should have at least two radio buttons, if they are used at all. The Part Type 
number is 12. 

The display rectangle of the radio button will be calculated automatically by 
supplying the upper-left coordinates (Min Y, Mia X, relative to the Dialog Box) of the 
Part, and setting the lower-right coordinates to 0,0. 

The label is placed on the right side of the radio button. Its descriptor may be as long 
as necessary but may not exceed one line. 

The PartValue has the initial setting of the button (0 = OFF, 1 = ON). 

The PartFlag has a value from to 32512. This value links the radio buttons 
together. Use a different value (in increments of 256) for each series of radio buttons. 

The Scroll Bar 

A scroll bar is a rectangle with an arrow at both ends* It causes an immediate result 
on the object it is controlling. The arrows are used to move the lever one notch at a time. 
A click of the Mouse on the grey area, above or below the thumb, will move the display 
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by the rmmber of pixels represented by the thumb. The lever, also called a thumb, may 
be dragged with the Mouse to a precise position. Its Part type niimber is 13. 

The display rectangle of the scroll bar sets its thickness, height or length depending 
on its orientation. 

The scroU bar is not labeled 

The PartValue indicates the actiial position of the thumb and ranges fi:t>m to 290. 

The PartFlag indicates whether a horizontal or vertical scroll bar or indicator will be 
displayed. The proper values are: 

Vertical indicator 

3 Vertical bar 

4096 Horizontal indicator 

7168 Horizontal bar 

The Static Line 

A Dialog Box may be labeled using a static line of text. This static line of text may 
not be modified at a later time. The Dialog Box label uses the current font for the 
characters. The maximum length of a static Hue is set to 64 characters by Micol 
Advanced BASIC, Its Part t3T)e number is 15. 

All static lines should be disabled by adding 32768 ($8000) to its ID number so they 
will not return Part numbers to the Event Loop. 

The display rectangle of a Static Line must be large enough to show the entire text 
without overlapping other Dialog Box Parts, 

To display a static text on one line, a rule of thxmib is to allow at least 20 pixels wide 
by 10 pixels in height for a character. For example, a Hne of text with 8 characters wiU 
need at least 160 pixels in length. 

To display a Line of static text on multiple lines, concatenate a carriage return (ASCII 
13) between each Hne. The next line of text wiU be placed 10 pixels below the preceding 
one. 

The PartValue and the PartFlag are imused (set to zero) with a Static line. 

A Static Line should be the first Part displayed when a Dialog Box appears on the 
screen. To do this, assign the highest Part ID number to the static line. This line of text 
will help the user immediately understand the purpose of the Dialog Box. 

The Edit Line 

An Edit Line is a rectangular box containinig information. It is often used to give a 
Pathname for operating system operations or to provide information in response to a 
query by the program. Its Part nximber is 17. 

The display rectangle of an Edit Line must be at least 20 pixels wide by 12 pixels in 
height for each character. For example, a line of text with 8 characters wiU need at least 
160 pixels in length. The next line of text wiU be placed 12 pixels below the preceding 
one- 
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The PartValue coatains the maxiinTim nxunber of characters that may be enteired 

The PartFlag is unused (set to 0). 

A Hne of static text should appear above an Edit Line to indicate what is expected as 
input. 

Defining the Dialog Box 
DIALOG (IntegerArray (, StringArray ( ) 

A Dialog Box is defined by the DIALOG command. DIALOG requires two arrays: 
an integer array and a string array to hold the necessary values. The integer array 
holds the coordinates of the Dialog Box and those of the Parts within it. The string 
array holds the labels of the Dialog Box Parts. 

Element zero of the passed integer array contains the Dialog Control Number, This 
Dialog Control Number instructs DIALOG as to what action to take, and controls which 
values are required in the passed arrays (see table 4.4.2). 

Dialog Control Numbers 

Element zero of the integer array passed to DIALOG must contain the Dialog 
Control Number. This Dialog Control Number determines the function of DIALOG and 
performs the following tasks: 

Table 4*4.2 Dialog Control Numbers 
Value Task 

Close the Dialog Box 

1 Create the Dialog Box 

2 Add a Part to the Dialog Box 

3 Romove a Part from the Dialog Box 

4 Enable a Part in the Dialog Box 

5 Disable a Part in the Dialog Box 

The Dialog Control Number assigned to element zero of the integer array passed to 
DIALOG will determine which fiirther values are required in the integer array: 

Close the Dialog Box (0) 

If the Dialog Control Number specified is zero, the current EHalog Box will be closed 
and disappear from the screen. The memory used by the Dialog Box will be released. 

Example: 

Array% (0) = {Close Dialog Box} 
DIALOG (Array% (, Array $ ( ) 
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Create the Dialog Box (1) 

This is the most important Dialog Control Number. If the Dialog Control Niimber 
specified is one, the system will create (but not yet display) a Dialog Box with the 
controls and labels defined in the parameter arrays passed to DIALOG. Once the 
MOUSE command is executed subsequent to the Dialog Box creation, the Dialog Box 
will be displayed. 

In order to create the Dialog Box, additional information is required and is stored in 
the parameter arrays. The integer array must contain the following information: 

Element one contains the Tm'nimnTn Y coordinate of the Dialog Box 
Element two contains the minimum X coordinate of the Dialog Box 
Element three contains the maximum Y coordinate of the Dialog Box 
Element four contains the maximxam X coordinate of the Dialog Box 
Element 5 holds the total number of Parts in the Dialog Box, Any Parts added to 
the Dialog Box during the execution of the program are NOT counted here- The 
other array elements contain the descriptions of the Parts in the Dialog Box. A 
Dialog Box may have as many Parts as necessary. 

• Element 6 is the identification(ID) number of the Part. This is the value passed 
back to the MOUSE command to inform you what the user response was. ID 
numbers must be unique for each Part and range from 1 to 255, 

• Elements 7 through 10 contain the local (relative to the Dialog Box) coordinates 
of the Part. The coordiaates are expressed in pixels. The coordinates are listed 
in this order: Y miniTrmTn coordinate, X minimum coordinate, Y maximum 
coordinate, X maximum coordinate. 

• Element 11 stores the Part Tyi)e Number (see Table 4.4.1)» 

Element 12 holds the Part Value (see the specific control). 

Element 13 contains the Part Flag (see the specific control). 

Element 14 holds the element number of the string array storing the label. Use 
zero if no label is required. 

lb define other Parts in the Dialog Box, repeat elements 6 through 14 in subsequent 
array elements for e nch Part until the number of Parts specified in element 5 are 
satisfied All Dialog Box Parts will appear in the reverse order in which they were 
defined Thus, the Part defined with tiie highest ID number will appear first and the 
one with the lowest ID number will appear last- 
Next, the elements of the string array storing the labels must be defined. These 
array elements contain the strings referenced in the integer array as specified in 
element 14 (and subsequent integer array elements). 

Example: 

PROC DialogBoxl {Define Dialog Box} 
{0 = Close, 1 = Create Dialog Box} 
Axray% (0) = 1 {Create the Dialog Box) 

Array% (1) - 99 {Y height of Dialog Box} 
Array% (2) - 319 {X width of Dialog Box} 
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Array% 


(3) - 50 { 


Array% 


(4) = 150 { 


Array% 


(5) - 2 { 


{Parti 


definition} 


Array% 


(6) - 1 { 


Array% 


(7) - 27 { 


Array% 


(8) - 2 { 


Array% 


(9) - 198 { 


Array% 


(10) = 317 { 


Array% - 


(11) - 15 { 


Array% 


(12) - { 


Array% 


(13) - { 


Array% 


(14) - 1 { 


{Part2 


definition} 


Array% 


(15) - 2 { 


Array% 


(16) = 27 { 


Array% 


(17) = 2 { 


Array% 


(16) - { 


Array% 


(19) - { 


Array% 


(20) - 10 { 


Array% 


(21) = { 


Array% 


(22) - { 


Array% 


(23) = 2 { 


{Part names} 


Array$ 


(1) = ^Dialog Box" 


Array$ 


(2) = ^^OK" 
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Y height of Dialog Box} 
X width of Dialog Box) 
Nuinber of Parts on panel} 

Part ID number} 

Y inin start position} 
X min start position} 

Y max start position} 
X max start position) 
Part type: StatText} 
Part value: unused} 
Part flag: unused} 
String array # for "Dialog Box''} 

Part ID number) 

Y min start position} 
X min start position} 

Y max start position} 
X max start position} 
Part type: Push Button} 
Part value: unused} 
Part flag: single/round} 
String array #2 ^OK"} 



(End of definition of the Dialog box} 
DIALOG (Array% {, Array$ ( ) 

After the Dialog Box is created, you may wish to fetch the Dialog Port handle 
returned in integer array elements zero and one of the integer array passed to DIALOG. 
The low part of the handle is in array element zero; the high part of the handle is in 
array element one. Be certain to save this handle if you wish to make TboLBox calls 

later. 

Example: <Program fragment> 
Array% (0) - 1 
{Create Dialog box} 
DIALOG (Array%(, Array$ ( ) 
(Get the Dialog Box Graf Port handle} 
DlgHdle_Low = Array% (0) {Low Handle} 
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DlgHdle_High = Array% (1) (High Handle} 
IMPORTANT 



If you are creatdng a Dialog Box, the Dialog Box will not 
be displayed until the MOUSE command, monitoring the 

Dialog Box, is executed 



Add a Part to a Dialog Box (2) 

A Dialog Control Number of two is designed to add another Part to a Dialog Box 
besides those that were included when the Dialog Box was created. The integer array 
passed to DIALOG must have the following entries; 

Element Part lype 

1 Part ID Number 

2 Minimum relative Y coordinate of Part 

3 Minimum relative X coordinate of Part 

4 Maximum relative Y coordinate of Part 

5 Maximum relative X coordinate of Part 

6 Part type (see Tables 4.4.1) 

7 Part flag (see spedfic Part) 

8 Part value (see specific Part) 

9 Element number in string array containing text display. 

Remove a Part from a Dialog Box (3) 

If element zero of the integer array contains a three, the Part number assigned to 
element one of the integer array will be removed from the current Dialog Box. 

Example: 

Array% (0) = 3 {Remove Dialog Part} 

Array% (1) = 3 {Part ID number to be removed} 

DIALOG (Array% (, Array$ ( ) 

Enable a Part in a Dialog Box (4) 

If element zero of the integer array passed to DIALOG contains a four^ the Part with 
the number assigned to element one of the array will be enabled. Thereafter, the user 
will be able to respond to this Part, 

Example: 

Array% (0) = 4 {Enable Part in box} 

Array% (1) ^ 3 {Part ID number to be enabled} 
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DIALOG (Array% (, Array$ ( ) 



Disable a Part in a Dialog Box (5) 

If element zero of the integer array contains a five, the Part with the number 
assigned to element one of the integer array will be disabled. Thereafter, the user will 
not be able to access this Part 



Example: 

Array% 
Axray% 

DIALOG 



(0) - 5 {Disable Part in box} 

(1) = 3 {Part ID nuinber to be disabled} 
(Array% (, Array$ (*) 



Programmers 



Micol Advanced BASIC uses the standard Parts defined 
by the Control Manager, lineEdit, and QuickDraw II Tbol 
seta. The Control Manager directs standard controls. 
The LineEdit Tool manages edit lines. QuickDraw 11 

displays the Statlbxt Parts. 



Monitoriiig the Dialog Box 



MOUSE (Integer_Array ( ) 

Once you have defined a Dialog Box, you must monitor it for a user response. Like 
monitoring the response to a Menu and Window, the MOUSE command is used to 
monitor Dialog Boxes. Unlike monitoring a Window or a Menu however, MOUSE is not 
placed within a loop to monitor a single response from the user; MOUSE will not return 
control to your program until the user has responded to the Dialog Box. Once the user 
has responded to the Dialog Box, the Part ID number (defined by you in the DIALOG 
command) will be returned in element zero of the integer array passed to MOUSE. 

When monitoring the Dialog Box with MOUSE, the Part ID Numbex received in 
element zero of the integer array passed to MOUSE is used to direct the program flow to 
the program code handling the action for that control. The Dialog Box is displayed until 
the user selects the close button and the program closes the Dialog Box. 

Example: 

{The Dialog Box is previously defined} 

DialogExit! = FALSE 

REPEAT {Display until True} 

MOUSE (EventRecord% ( } 

ItemID% » EventRecord% (0) 

CASE_OF ItemID% 

DO 1 {OKAY Button} 
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DialogExit! - TRUE 
ENDDO 

DO 3, 4, 5 {Check Boxes} 
{ GetDitemValue } 

TOOLBOX (21,46:0,tl,tO,ItemID;ItemValue) 
{ItemValue ^ if CheckBox is not checked, 

ItemValue = 1 if CheckBox is checked - 
If ItemValue - then ItemValue = 1 
If ItemValue = 1 then ItemValue - } 
ItemValue = ABS (ItemValue - 1) 
{ SetDitemValue } 

TOOLBOX (21, 47 : ItemValue, tl, tO, ItemID) 
ENDDO 
END CASE 
UNTIL DialogExit! {Radio_Buttons } 

See the demonstration program DIALOG to see how to use the Dialog Control 
Nimibers and CONTROLS to see how to define the dififerent types of controls. These 
example programs are on the MAB.SUPPORT disk in folder Desktop.Samples/. 
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Part Five: The Apple IIGS ToolBox 
Chapter One 

Direct Toolbox Access 
Overview 

This chapter demonstrates how to use Micol Advanced BASICS TOOLBOX 
command to get direct access to the Apple IIGS TbolBox. 

Defining the ToolBox 

What is the TbolBox? The ToolBox is a series of routines designed to perform specific 
tasks. Each particular task, like memory management or graphics, is divided into a 
specific TooL Each Tool is given a unique ID number. Within each Tool are specific 
Functions which perform individual tasks. Each Function within a particular Tool set is 
also designated by a unique ID number 

For example, Tool number two is the Memory Manager and QuickDraw II, which 
does Super High Resolution graphics, is Tool 4, Function number two within each Tbol 
starts up the Tool, while Function 15 in QuickDraw II returns the contents of a color 
table. 

Books describing IbolBox functions will be necessary to write Micol Advanced BASIC 
programs that use the Apple IIGS Toolbox, The Hst of Ibols appears in Table 5.2.1 and 
5.2.2, (As this manual goes to press, thirty-three tool sets have been defined; of these, 
thirty- two sets were released in ROM and the IIGS System Disk v5.04.) 

The Universal TOOLBOX Command 
TOOLBOX (ToolNum, FuncNum [rPush List] [;Pull List]) 

The TOOLBOX command is designed to call virtually any Tool and consists 
essentially of four parts. The first part consists of the Tbol Number. The second part is 
the Function number within the Tool. The third part, the Push List, consists of the 
parameters required by the Tool Function, and the forth part, the Pull List, is a set of 
integer variables which will contain the values returned by the Tool Function itself. 

The first argument, the Tool Set Number, is an integer literal (expressed in decimal 
or hexadecimal) or integer variable. 

The second argument, the Tbol Fxmction Number, is an integer literal (expressed in 
decimal or hexadecimal) or integer variable. Any value greater than 255 ($FF) generates 
an error 
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Art optional list of integer literals (in dedmal or hexadecimal) or integer variables, 
separated by commas, follows the Fxinction Number. This list is separated from the 
Function number by a colon (:) and is a set of values that will be pushed onto the TbolBox 
stack- 
Last comes an optional list of integer variables, separated by commas, which will 
contain the values returned by the Tool Function- A semi-colon (;) precedes this Hst. 

Most Ibol Functions require values to be placed onto the IbolBox stack before the 
Function can be used. These values are often a four-byte memoiy location which may be 
represented within two two*byte integer literals or variables. Toolbox reference manuals 
list the values to be pushed or pulled from the stack in terms of words and long words. A 
word is equivalent to an integer, and a long word is equivalent to two integers. For the 
most part with the TOOLBOX command, long integers are treated like short integers. 

Determining the Tool and Function Numbers 

In any TdoIBox reference manual, a Function is referenced in terms of a name and a 
call number. This call number is iised by assembly language programmers to make the 
call to the Tbol Function. 

This call number is a hexadecimal number with the Function number and Tbol 
number appended. You can easily luiappend this number to determine the Ibol number 
and Function number for use with the TOOLBOX command. 

Let's say that the call number of a particular Tool Function is $2C03 (SysBeep). The 
dollar sign simply means that the niunber is hexadedmaL The n^t two characters in 
the number are the hexadecimal value of the Function Number, or $2C (44 decimal). 
The following two letters are the hexadecimal value of the Tbol Number or $03 (3 
decimal). Therefore, in this example, the Tool nimiber is three, and the Fimction 
number is 44. Please note that TOOLBOX can accept either decimal or hexadecimal 
numbers, so there is no need to make any conversions. 

Example: 

TOOLBOX (03, 44) {SysBeep $2C03} 

T e Push List 

The Push List of the TOOLBOX command is used to pass values to the particular 
Tool Function. Every description of a Tbol Fiinction will describe what values have to be 
pushed unto the stack. These are the values that go into the TOOLBOX Push List. 

Values contained within the Push List will consist of either integer literals or integer 
variables. An integer is the same as a word that needs to be pushed onto the TbolBox 
stack. Two short integers must be used to equal a long word. 

Be very carefdl when specifying values for the Push Stack. There is a one-to-one 
correspondence between values that are contained in the TOOLBOX command, and 
values that are pushed onto the ToolBox stack as defined in any TbolBox reference 
manual. TOOUBOX pushes values onto the stack in the order they are specified. 
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Example: 

Colour - 15 {Clear to White} 

TOOLBOX (04, 22: Colour) {ClearScreen $1504} 

The PuU List 

Many Tool Punctions return values after their work is done* The values from the 
Tool Function will be returned in the integer variables in the Pull List in the order they 
were defined within the TOOLBOX command. 

Example: 

Rnd_Nuiu% = 

TOOLBOX (04,134: 0; Rnd_Num%) {Random $8604} 

Example: 

XCoord% - 240 

YCoord% - 120 

Pixel% - 

{GetPixel $8804} 

TOOLBOX (04,136: 0, XCoord%, YCoord%; Pixel%) 

Error Checking 

If the call to the Tbol Function is successful, zero wil be returned in True^Value 
(locations 202 and 203). If the Tbol Function should return an error, the error value wiU 
be retiimed in True^Value in LSB, MSB order. MSB (location 203) will be the Tbol 
Number which returned the error, not always the Ibol that was called. 

PEEK location 202 to determine if the call was successful. If the value is zero, the 
call was successful, otherwise you should be able to determine the problem. 

TOOLBOX and Long Integers 

The TOOLBOX command wiU use long integers when the LONGINT compiler 
option is specified. Only two bytes (one word) from the long integer's value will be used, 
usually the two least significant. The Greater Than symbol (>) may be used to reference 
the most significant word in the long integer; if the long integer is storing an address, 
this is the bank number of the address. 

Example: <Program fi:agment> 

PROGRAM Show_LongInt 

S LONGINT 

(Get the address of the pointer} 

Address% = ADDR (Address% ( ) 

TOOLBOX (14, 19: >Address%, Address%} {ShowWindow $130E} 
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Long integers may be used in this manner only with the TOOLBOX command. 

Future ToolBox Additions 

The TOOIiBOX command is a very versatile command. It was designed to let you 
take advantage of present and future Tool sets to come &T>m Apple Computer Inc. or fix)m 
third-party companies, 

Allocatiiig ToolBox Buffers 

Many TbolBox calls need the use of a supplied buffer to accomplish their tasks. 
Essentially, there are two methods you may use to fetch memory for a ToolBox call. 

The more difficult method to fetch this memory is to either use a TOOLBOX call to 
the Memory Manager, or the GET_MEM command. This method needs to be used if you 
are fetching Direct Page memory for the Tool, otherwise, use the easier method. 

We will outline the easier method here- Allocate some memory within a dummy 
array with the DIM statement. Be certain this array is large enough for its work and do 
not use it for any other purpose, as internal values may become corrupted by the ToolBox 
call. The ADDR command may then be used to get the address of this dummy array, 
and this address may then be passed to the Tool calL 

The following example program below should answer any questions you may still 
have about the TOOLBOX and ADDR commands- The example below uses 
Miscellaneous Tool (Set 03) to read the time and date as an ASCII representation, and 
then displays this time and date to the screen. 

Example (line numbers are for reference only): 

1. PROGRAM Display^Time 

2. @ LIST 

3. DIM ToolBox_Buf% (10) 

4. Adx% - ADDR (ToolBox_Buf% ( ) 

5. Bank_Nuinber% - PEEK (202) 

6. TOOLBOX (3, 2) {Turn on Misc. Tools} 

7. {ReadASCIITime $Oe03} 

8. TOOLBOX (3, $0E: Bank_Nuinber%, Adr%) 

9. AdrS =- ADDR (Toolbox_Buf % ( ) 

10. HOME 

11- PRINT ""The Current time is "; 

12. FOR Loop_Ctr = AdrS TO Adr& + 19 

13. Char « PEEK (Loop_Ctr) 

14. Char$ ^ CHR$ (Char) 

15. PRINT Char$; 

16. NEXT Loop_Ctr 
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17. PRINT 

18, {Turn off Misc Tools} 

19. TOOLBOX (3, 3) 

20, END 

How this program works*** 

1. At Hne 3, a 23 byte buffer is defined for the TbolBox output This biiffer should 
never be used as an array. 

2. At line 4, the address of the TbolBox buffer is determined as an integer value. 

3. At line 5, the bank number of the ToolBox buffer is obtained. 

4. At line 6, the Miscellaneous Tbol set is started 

5. At hne 8, the ReadASCIITtme function call from the Misc. Tools is done by pushing 
the bank number and the address of the buffer onto the TooIBox stack as 
required by this Tool Function. 

6* At line 9, the fiiU address of the ToolBox buffer is determined as a real value. We 
need the real address to be able to PEEK the Tool Fimction results from 
memory. 

7, At lines 12 - 16, the time and date returned by the Tool are displayed- Note the use 
of PEEK within the loop. Because of the way Micol Advanced Basic parses a 
statement, we cannot use an integer variable at line 13, because, if we did, 
PEEK would try to take the integer value of Loop_Ctr, a value too great for an 
integer, and we would therefore receive an error. 

8. At hne 19, the Misc. Tools is shut down. It is wise to always wait until the end of 
your programs before performing any shutdowns as these Tools may also be 
used by the run time routines. 
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Chapter Two 
Tool Set Tables 

Some of the Ibols listed below are used automatically by the run time routiiies: do 
not start them up or shut them down using the TOOI-BOX command. Use the 
TOOLBOX command to start or shut down the tools that have no Micol Advanced 
BASIC equivalent or are not started by a run time routine (if the respective command is 
not active in your program). 

Startup notes: You must observe the following: 

The following Tools are always necessary and should never be shut down by your 
program: Tool Locator^ Misc. Tools, Memory Manager, Text Tools, and SANE< 
The Desktop Tools (Event Manager, Line Editor, Window Manager, Menu 
Manager, Dialog Manager, Scrap Manager, and Control Manager) are activated 
when one of these Micol Advanced BASIC commands is executed: DIALOG, 
MENU, or WINDOW, 

• The Sound Tool Set is activivated by the NOISE command 

• The Soxmd Tool Set and the Note Synthesizer Tool are activated by the MUSIC 
command, 

• QxiickDraw 11 is started by the HGR or HGR2 command- 
Shutdown Notes: As a general rule, shutdown of the Tools is done ra the reverse 

order as they were started up. You must observe the following: 

The Tools started by the Library routines are all deactivated and memory is 

deallocated by the END, STOP or BYE command 
- The Desktop and Graphics Tools are deactivated by TEXT. 
■ The Sound Tool Set and the Note Synthesizer Tool are both deactivated by the 

SILENCE command 

The memory necessary for the Tool is deallocated automatically when the Tool is 
shut down. 

The tables in the following pages enumerate the Ibols, their startup, shut down 
order, and the memory needed by each set. 

Legend: 

• '^AN" means "After N", N is a Tool Number that indicates that the tool with that 
number must be started before this one, 

• (d) indicates a Desktop command (MENU, WINDOW or DIALOG) 



Part Five: The Apple IIGS ToolBox 



218 



Chapter Two: Tool Set Tables 



Table 5.2.1 Startup list 



bol# 


Tool Set Name 


Started by 


1 


Tool Locator 


library 


2 


MeTnory Manager 


Library 


3 


Miscellaneous Ibol 


Library 


4 


QuickDraw II 


HGRorHGR2 


5 


Desk Manager 


(d) 


6 


Event Manager 


(d) 


7 


Scheduler 


Library Routine 


8 


Sound Ibol Set 


NOISE 


9 


Apple Desktop Bus 


Library Routine 


10 


SANE 


Library Routine 


11 


Integer Math 


Library Routine 


12 


Text Tools 


Library Routine 


13 


Internal Use 


Cannot Be Called 


14 


Window Manager 


(d) 


15 


Menu Manager 


(d) 


16 


Control Manager 


(d) 


17 


System Loader 


Do Not Call 


18 


QuickDraw 11 Aax. 


TOOLBOX (18,02) 


19 


Print Manager 


TOOLBOX (19,02) 


20 


Line Edit 


(d) 


21 


Dialog Manager 


(d) 


22 


Scrap Manager 


(d) 


23 


Stnd File Operation 


TOOLBOX (23.02) 


24 


(Not Defined) 




25 


i-^ote Synthesizer 


MUSIC 


26 


Note Sequencer 


TOOLBOX (26,02) 


27 


Font Manager 


TOOLBOX (27,02) 


28 


Tjist Manager 


TOOLBOX (28,02) 


29 


ACE Ibol 


TOOLBOX (29,02) 


30 


Resource Manager 


System Loader Al 


31 


(Not Defined) 




32 


MIDI Ibol 


TOOLBOX (32,02) 


33 


Video Overlay Card 


TOOLBOX (33,02) 


34 


Ttext Edit Tool 


TOOLBOX (34,02) 



Order 

1 

2 

3 

4 

18 (Last) 

5 

A3 

A21 

Al 

A2 

Al 

Al 

NA 

6 

8 

7 

NA 

A4 

15 

9 

10 

12 

11 

A21 

A21 

14 

13 

A2 



A21 

A5 

A6 
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Table 5.2.2. Shutdown List 



ool# 


Tool Set Name 


Shutdown by 


Order 


1 


Tool Locator 


Library Routine 


29 (last) 


2 


Memory Manager 


Library Routine 


25 


3 


Miscellaneous Tbol 


Library Routine 


21 


4 


QuickDraw II 


TEXT 


19 


5 


Desk Manager 


TEXT (if started as (d) 


First 


6 


Event Manager 


TEXT if started as (d) 


17 


7 


Scheduler 


Library Routine 


20 


8 


Sound Ibol Set 


SILENCE 


11 


9 


Apple Desktop Bus 


Library Routine 


28 


10 


SANE 


Library Routine 


24 


11 


Integer Math 


Library Routine 


27 


12 


Text Tool set 


Library Routine 


20 


13 


Internal Use 


Cannot Be Called 


NA 


14 


Window Manager 


TEXT if started by (d) 


16 


15 


Menu Manager 


TEXT if started by (d) 


14 


16 


Control Manager 


TEXT if started by (d) 


15 


17 


System Loader 


Do Not Call 


NA 


18 


QuickDraw II Aux. 


TOOI.BOX(18,03) 


18 


19 


Print Manager 


TOOT.BOX( 19,03) 


3 


20 


LineEdit Thai 


TOOLBOXi(20,03) (d) 


13 


21 


Dialog Manager 


TOOLBOX(21,03) (d) 


12 


22 


Scrap Manager 


TOOLBOX(22,03) (d) 


6 


23 


Stnd Pile Operation 


TOOI.ROX(23,03) 


7 


24 


(Not Defined) 






25 


Note Synthesizer 


SILENCE 


10 


26 


Note Sequencer 


TOOLBOX(26,03) 


9 


27 


Font Manager 


TOOT,BOX(27,03) 


4 


28 


List Manager 


TOOLBOX(28,03) 


5 


29 


ACE Tbol 


TOOT.BOX(29,03) 


23 


30 


Resource Manager 


System Loader 


22 


31 


(Not Defined) 






32 


MIDI Ibol 


TOOLBOX(32,03) 


8 


33 


Video Overlay Card 


TOOT,BOX(33,03) 


A5 


34 


Text Edit Tool 


TOOLBOX(34,03) 


2 
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Table 5.2.3 Tool Sets 


Dool# 


Tool Name 


04 


QuickDraw II 


06 


Event Manager 


08 


Sound Tbol Set 


10 


SANE Tool Set 


14 


Window Manager 


15 


Menu Manager 


16 


Control Manager 


18 


QuickDraw II Auxiliary 


19 


Print Manager 


20 


TJneRdit Ibol 


21 


Dialog Manager 


23 


Standard FHe 


25 


Note Synthesizer 


26 


Note Sequencer 


27 


Font Manager 


29 


ACE Tool 


31 


(Not Defined) 


32 


MIDI Ibol 


33 


Video Overlay Card 


34 


Text Edit Tool 



Direct Page Memory Requirements 

Direct Page Allocation 

Yes, 768 bytes 

Yes, 256 bytes 

Yes, 256 bytes 

Yes, 512 bytes 

No, Shares Ibol 06 Direct Page 

Yes, 256 bytes 

Yes, 256 bytes 

No, Shares Tool 04 Direct Page 

Yes, 512 bytes 

Yes, 256 bytes 

No, Shares Tool 16 Direct Page 

Yes, 256 bytes 

No, Shares Tx>l 26 Direct Page 

Yes, 768 bytes 

Yes, 256 bytes 

Yes, 256 bytes + meraory for buffers 

Yes, 768 bytes + memory for buffers 

Unknown 

Yes, 256 bytes 
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Part Six: Program Management 
Chapter One 

Program Debugging 
Overview 

This chaper is designed to help you debug your programs. 

What Is Debugging? Debugging is the act of finding errors within a program. 

In general, two classes of errors can occur in a program; syntax errors and logic 
errors. 

Syntax errors occur when the syntax rules of the language are violated and are 
caused mainly by typing errors or by a misunderstanding of the rules of the language. 
These errors are almost always very easy to solve and will not concern us here. 

Logic errors are much more difficult to determine than syntax errors and ocoir when 
a program is not properly designed to solve the problem in question. Logic errors cause 
the program to give different results and/or behave differently than what was expected. 

No language system can find such logic errors because no language system can do 
what a human can do> think. The most a language system can do is to give the 
programmer some tools to help him/her find these logic errors. This is what Micol 
Advanced BASIC does and this is the subject of this chapter. 

Debugging Statements 

Often, a variable has a different value than is intended, or an area of code has 
executed when it should not have executed, or vise-versa. 

Programs do exactly what you teU them to do; they do not do what you think you tell 
them to do. This is very often the cause of logic errors; the progr^^nmer has told the 
computer to do something other than had been intended. Do not assume that any code is 
automatically correct, this is a big mistake. 

Another cause of logic errors is that the programmer has devised an incorrect 
solution to the problem* The program operates as intended, but incorrect results are 
coming out This is a more serious problem, and more difficult to solve. Once the 
problem is located, the code must be rewritten. 

The following statements are designed to help inform you where you are going 
wrong; they cannot find the problems themselves. Use these commands wisely, and your 
job wiU be a lot easier. 
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BELL 

BEILL can be a good tool to help you find your logic errors. Just place BELL in the 
section(s) of code where the program seems to be malfunctioning. If the speaker beeps 
when it should not or fails to beep when it should, a bug may have been found in the 
program. The beep gives yon an aural message telling that something may be wrong. 

Example: 

IF PEEK (202) - 2 THEN BELL 

PRINT 

Insert a PRINT statement at strategic points in the program to determine what the 
contents of a particxilar variable are. 

Example: 

Alpha% - PEEK (True_Value) 
PRINT '"Alpha% " "; Alpha 

STOP 

STOP halts the program's execution, prints the line number where the program 
halted, and returns control to the Command Shell while using the programming 

environment. 

Line number information can be valuable information in debugging as it is 
sometimes the case that a particular line should or should not be executing at a certain 
point in the program's execution. Then it's necessary to trace the logic in your program 
to determine why the program flow got to where it did 

This is what is known as setting a break point, and is the most frequently used 
debugging technique in assembly language programming* Break points may also be 

useful in high level debugging. 

STOP may be placed anywhere in a prograi^ as it closes all text files currently open 
and sets the screen to text mode. 

Example: 

Variable - 3 

IF Variable - 3 THEN STOP 

TRACE 

TRACE will print the sequential line numbers of the program as the line or 
structured loop statement is executing. Tracing a program's flow can be a great aid in 
determining the program's actual logic. 

TRACE may be placed anywhere in a program and follows the flow of execution used 
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in the program. 

To use TRACE, place it before the location from which you wish to begin the trace of 
your program- Any code executing before TRACE will not be displayed. 

The tracing may be paused by pressing any non-Control character. Restart the 
tracing by pressing any non-Control diaracter again. 



WARNING 



Do not use the OPTEVHZ compiler option as it hinders 
the generation of line information required by TRACE, 



Example: 

PROGRAM Try_Trace 

PRINT ^This program will be traced" 

HOME 

TRACE 

FOR Niamber% = 1 TO 4 

PRINT ''N\iinber% = "; Number % 
NEXT Number % 

NOTRACE {Turn off the TRACE} 
END 

STRACE 

STRACE stands for SuperTRACE. STRACE will print the sequential line numbers 
of the program and the text of the line that is executing to the current output device as 
the Une is executed. 

lb use the STRACE command, place it before the location at which you wish to 
begin the trace of your program. Any code executing before the STRACE will not be 
displayed. STRAC .1 may be placed anj^where in a program 

STRACE follows the flow of execution used in the program; so the Unes will not be 
shown consecutively. 

The tracing may be paused by pressing any non-Control character. Restart the 
tracing by pressing any non-Control character again. 



WARNING 



STRACE takes the text it displays Gcom the program 
currently in the Text Editor This means tiiat the 
program you wish traced must be in the Itext Editor, 
which is normally the case. Do not use the OPTIMIZ 
compiler option. 
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Example: 

PROGRAM Try_S TRACE 

STRACE {Turn on the STRACE} 

HOME 

FOR NuitLber% - 1 TO 2 

PRINT NuiTaDer% 
NEXT Niiinber% 
NOTRACE 
PRINT 

PRINT ""This program has been traced" 
END 

The above program produces something like this on the screen: 

/<3>H0ME\ 

/<4>F0R NuirLber% - 1 TO 2\ 

/<5> PRINT Number%\ 

1 

/<6>NEXT Nuinber%\ 

/<4>F0R Nuiiiber% - 1 TO 2\ 

/<S>PRINT Number%\ 

2 

/<6>NEXT Nuinber%\ 

/<7>N0TRACE\ 

NOTRACE 

NOTRACE turns off the effects of a TRACE or STRACE. The number of the line 
and its text of code will no longer appear after NOTRACE is executed. 

Example: (see example under TRACE and STRACE.) 
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Chapter Two 

Program Optimization 

Overview 

This chapter disoisses some simple tricks to help you maximize the speed of your 
programs while at the same time iniiiimiziiig the program size. 

Saving Memory 

Because of the large amount of memory availahle to the Apple II GS, you may never 
have to worry about memory used for either programs or data. Under Micol Advanced 
BASIC f a program, may have a maximum of over one million bjrtes and data space is 
limited only by the available memory in the machine. 

However, if you have a system with only 768K, this section may be of use to you. 
Consider buying more memory as soon as your finances permit. 

Generally, the tricks to help save memory are the same as in Applesoft BASIC. 

Working within the Editor's Workspace 

The text editor has enough work space for about 4000 lines of code. Use INCLUDE 
or CHAIN in the program if the program exceeds 3000 Hnes. 

Saving Space in a Program 

Use the OPTEVHZ compiler option once your program is free of bugs; this can 
shrink your programs as much as one-third. If limited Space is a problem during 
program development, you may use this compiler option to save memory, but 
determining where run time errors occur will become much more difScult. 

• Avoid the use of the ERROR compiler option. The only function this compiler 
option has is in regards to the RESUME command, but ERROR causes a 
significant amount of code generation. You will have to handle your error 
recovery in a different fashion* 

Analyze your programs for repeated code. It may be possible to create one 
subroutine that will do the work of several portions of your program. 

Use arrays as rarely as possible. If you must use arrays, use integer arrays 
whenever possible. Do not make arrays any larger than you have to, 
Avoid DATA statements. DATA statements require significant memory. Data 
may just as well be stored on disk and recalled at run time. 

• Do not use the EXTEND or the LONGINT compiler options if very large arrays 
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are used within your program. 

• Avoid mixed aritlunetic. Mixmg reals and integers within a statement forces the 
Compiler to generate extra code, code that may possibly be avoided 

As with any programming language, code efficiently. 

Speeding Up Your Programs 

Certain methods may be used to make a program execute more qidckly Some of the 
tips mentioned above apply here too. 

• Make use of the OPTIMIZ compiler option as soon as your program is 
completely free of bugs. The code required for debuggiag purposes usiially takes 
significant time to execute. Once your program is debugged, this code no longer 
has a useful purpose and may be eliminated. 

Do not mix your arithmetic. If calculating in real, be consistent with real; 
likewise for integers* 

• Use integer variables whenever practical, Micol Advanced BASIC has its own 
built-in integer routines. The average increase in speed over real arithmetic may 
be as great as 300%. 

• Use arrays wisely. Some time is needed at run time to calculate the address of 
the array element. However, if you have an algorithm which is faster than 
another and uses arrays, feel fi^ee to use them 

Avoid disk access as much as possible. If you have frequent disk access with the 
S£ime file(s) being read again and again and you also have a lot of available 
memory, make use of a RAM disk together with the COPY command to transfer 
the files from a static disk to the RAM disk before your program reads these files- 
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Chapter Three 

Program Segmentation 
Overview 

This sectioa shows how to segment both soiorce code and executable load modules 
under Micol Advanced BASIC and how to conceive large programs which would 
otherwise be very difficult to do. 

Chaining Source Code Files 

For very large programs, it may be necessary to segment your source code icito two or 
more portions in order to manage the source code within the Tfext Editor. Micol 
Advanced BASIC has two methods to allow you to segment your program code: chaining 
text files, and creating a library of modules. Because the creation of library modules has 
been discussed in Part Three, Chapter 9 in this manual, it will be only briefly discussed 
here. 

Segmenting the Source Code Files 

In order to segment the source code file, you must first decide where you can logically 
break the program. You must make every attempt to keep subroutines intact. 

Using the Text Editor, break this large program into several smaller source code files. 
To be safe, keep the original file safe just in case something goes wrong. 

Then, simply terminate each source code segment, except the last, with a CHAIN 
statement, using the next source code filename as the CHAIN string parameter. 

The second, and subsequent source code file(s) begin without a PROGRAM 
statement.. The next file finishes with an END or with another CHAIN if another file is 
to be chained, 

CHAIN StringL_Uteral 

The CHAIN statement must be the only statement on the line. It should be the last 
statement in the file: any subsequent line(s) of code following the CHAIN statement wiU 
be ignored by the Compiler 

Striag_Literal must be the Pathname of the soinxe code file you wish to compile after 
the previous source code has fibcdshed compiling- The only accepted parameter to 
CHAIN is a string literal; a string variable will be rejected by the Compiler. 

The file referenced must be online at the time of compilation, otherwise the 
appropriate operating system error will occur. 

The Compiler displays the message "Chaining <Pathname>" before it starts reading 
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the file to be chained. 

Example: 

(Contents o£ fllo: Chainl) 

PROGRAM Chain^Example 

@ LIST 

FOR Ctr% - i TO 10 

PRINT Ctr% 
NEXT Ctr% 
CHAIN ^/RAM5/Chain2" 

(Contents of file: /RAM5/Cha±n2) 

FOR Ctr% = 11 TO 20 

PRINT Ctr% 
NEXT Ctr% {End of chained program} 
END 

How to Debug a Chained Program 

The Compiler does not number the Hnes of a segmented chained program the same 
way the Editor does; the Text Editor always begins numbering from the first hue in the 
editor buffer. 

During compilation, the chained file is treated as if it were a part of the previous file. 
This means that the sequential line numbers continue uninterrupted. If an error with a 
specific line number within a chained file occurs during execution, you will have to 
recalculate its editor line number to be able to correct the problem in the Editor. The 
same situation is true of syntax errors. 

Consider using the INCLUDE statement as an alternative method of compiling 
large source code files. See Chapter Nine in Part Three for additional information. 

Segmentiiig Executable Code Files 

Micol Advanced BASIC programs may be a maximum of about one megabyte of 
memory. However, because of a limitation of the Apple IIGS microprocessor, a single 
program code segment may only occupy a maximum size of 64 kilobytes (one bank) of 
memory. The variable space is separate and is not affected by this limitation. 

The vast msgority of programs will not require a program space larger than 64 
kilobytes, however, some will. Micol Advanced BASIC overcomes this 64K limitation 
with the creation of executable program segments. 

A segment is a large, self-contained program section. The segment is used to break a 
program when it can no longer fit in one memory bank (64K). 

A program using segments need not be broken up into different program files as 
could be expected, but, space permitting, may be stored in a large continuous file. 
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The Compiler resets its internal program counter to zero when it compiles a new 
segment and generates code that will cause the Loader to load this program segment as 
a separate entity and store its loading location in a suitable location. 

How to Segment a Program 

A Micol Advanced BASIC program may have up to sixteen segments sequentially 
numbered from to 15, Each segment is given a sequential value by the Compiler; take 
note of this number as it will be needed to start the execution of the segment. The 
Compiler will display a message when it recognizes a new segment, and will display the 
number given to the segment. 

Each segment shares the entire variable space with all other segments, so any 
change in global values in one segment will also be recognized in the others. 

The executable code of segment zero (the starting segment) should not be larger than 
50K to leave room for maintenance. All segments should leave room for enhancements 
of current features, and additions of new features. If the segment is too large for a single 
memory bank, the Linker will report that program space is exceeded- 

The firat segment containing the line PROGRAM Identifier is segment zero; 
execution always begias with segment zero. Compiler directives, declaration of literal 
data, type identifiers, and DIMension statements may appear only in segment zero. 

Because one segment cannot have direct access to the Functions, Procedures and 
Routines of another segment, all segments must be self-contained. Functions, 
Procedures and Routines necessary to one or more segments have to be duplicated in 
each of the segments needing them. 

You may use the CUEAR statement only in segment zero; otherwise the program 
may crash. 

SEGMENT [Identifier] 

The SEGMENT statement forces the Compiler to segm.ent a program. It must be 
the first and only statement on a line of code, 

'. -3GMENT may have an optional segment identifier The segment identifier should 
be a digit or word which describes the segment and is designed to help in documentation; 
it is ignored by the CompUen 

The ke3rword SEGMENT signals the end of the preceding segment and the start of 
the new one. When the Compiler encoimters the reserved word SEGMENT, it 
generates code which will inform the Micol system loader to load that segment of code as 
a separate entity, and to set the program counter of the microprocessor accordingly. 

Using a Segmented Program 

Like a Function or Procedure, a segment will not execute by letting the program flow 
reach the SEGMENT statement; the segment must be called using CALL, 
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CALL Segment^Number 

The CALL statement branches the program flow to the segment number indicated. 
Segment_Number must be a digit between and 15, If the segment ninnber is not of 
this range, an error will be signaled during compilation. 



WARNING 



Do not use the CALL statement from a Function, 
Procedure, or Routine, as the maintenance done at the 
end of the modules has not been completed. 



Example: 

PROGRAM Segment_Exl 

{This is segment zero} 

IF Counter% - THEN ROME {Want only one HOME executed} 

IF Counter% < 5 THEN BEGIN 

PRINT '^Counter - "; Counter% 

PRINT '^Start of segment zero" 

FOR Ctr% = 1 TO 100 
PRINT Ctr% 

NEXT Ctr% 

CALL 1 {Going to Segment One} 
END IF 
END 
SEGMENT One 

PRINT '^Start of segment one'' 

FOR Ctr% ==- 101 TO 200 
PRINT Ctr% 

NEXT Ctr% 

CALL 2 {Going to Segment Two} 
SEGMENT Two 

PRINT ^'Start of segment two" 

FOR Ctr% = 201 TO 30 
PRINT Ctr% 

NEXT Ctr% 

Counter% = Counter% + 1 

CALL {Going to top of program} 
END 

Tins program simply prints the segment number followed by the sequential values 



Chapter Three: Program Segmentation 231 



five times. Note that the counter is incremented in the final segment, and the test is 
done in the program segment. 

If another segment has been called using the CALL statement, and the program 
must return to the statement following the original CALL, use LRETURN. 

LRETURN 

LRETUKN (for Long RETURN), similar to RETURN, instructs the program to 
return to the statement following the CALL statement that called this segment. Only 
one LRETURN statement should appear in a segment. 



WARNING 



LRETURN must never be used to end a Function, 
Procedure or Routine as imexpected results will occur. 



Unlike RETURN, no automatic error handling is done with LRETURN, so be 

certain there is a segment to return to. 

Example: 

PROGRAM Seg_Exainple2 
{This is segment zero} 
IF Counter% = THEN HOME 
IF Counter% < 5 THEN BEGIN 

PRINT Counter% == ;Counter% 

PRINT ''Start of segment zero" 

FOR Ctr% = 1 TO 100 
PRINT Ctr% 

NEXT Ctr% 

CALL 1 
END IF 

END {Terminate each segment with END or LRETURN} 
SEGMENT One 

PRINT ^'Start of segment one" 

FOR Ctr% = 101 TO 200 
PRINT Ctr% 

NEXT Ctr% 

Counter% - Counter% + 1 
LRETURN {Go back to Segment Zero AND finish} 
END {End of program} 
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Chapter Four 

Linking Assembly Language Programs 

Overview 

Sometimes, a specific task cannot be performed by a higher level language or even 
greater speed is needed than is possible in a higher level language. 

In these cases, a good solution is to integrate (or link) an assembly language modiJe 
into your program. Under Micol Advanced BASIC, it is very easy to link in machine 
language programs you have developed. 

Linking in the Assembly Language Program 
LINKPathName 

The LINK statement Hnks in the assembly language program specified by 
PathName, PathName must be a string literal and is the complete Pathname of the 
assembly language file to be linked. The file must be online at compilation time. If it 
cannot be found, the Compiler will signal an error. The assembly language program 
must be already assembled and error firee. 

The Compiler wUl indicate, "Linking file^ Pathname when it is linking a Micol Macro 
file into a Micol Advanced BASIC program. 

Example: 

LINK ^^/Assm.Prog.Util/ClrScreen.B'' 



IMPORTANT 



Micol Advanced BASIC for the GS uses assembly 
language files of type MCL ($F1) written with the Micol 
Macro GrS assembler only. If you ao not have this 
assembler, then you may purchase one directly from us. 



How to write an assembly language program to be linked into a Micol Advanced 

BASIC program: 

1. Write the assembly language program as required: 

a. Save all the registers at the start of the assembly language somrce code. Note 
that in Micol Advanced BASIC, the CPU is in 8 bit accumulator mode and 16 
bit X and Y registers mode 

b. At the end of your assembly language code, restore all the registers to the 
values they had before the start of the assembly language routine 
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c. Do ^M use an RTL ($6B) or RTS ($60) instruction to end the program; just let 
the assembly language code '*fall" through. The Micol Advanced BASIC 
program will resume on its own 

d. Thoroughly test this program for any errors. 

2, Link the assembly language file into the Micol Advanced BASIC program: 

a. Using the LINK statement, link this assembly language module into your Micol 
Advanced BASIC program where it is required. We recommend allocating a 
special Procedure for the assembly language module 

b. Remember, it is the MCL file (type $F1) which gets linked in, not the assembly 
language soxnrce code text file. 

Getting a Direct Page 

An area of 256 ($100) bytes in memory bank zero is reserved for use as a Ettrect Page 
for yoiir assembly language programs and is placed directly above the one used by Micol 
Advanced BASIC. 

How to Use this Direct Page 

Simply add $100 (256) to the current Direct Page Register upon entry of your 
machine language program and subtract $100 fix)m the Direct Page Register upon 
exiting your assembly language program. 



WARNING 



If you alter the value in the Direct Page register, be 
certain you reinstate it exactly as it was before or your 
Micol Advanced BASIC program is certain to 
malfunction. 



On the system disk marked /MAB,SL^'PORT, in folder Demo.Files/Prg.Examples is a 
file called LTNKDEMO which demonstrates the use of assembly language routines with 
Micol Advanced BASIC. You may want to take a look at this file. 
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Chapter Five 

Creating Independent Programs 
Overview 

This chapter tells how to take a compiled Micol Advanced BASIC program out of the 
programming environment - making it "stand alone", and execute it with a program 
launcher such as the Finder or as a turnkey system. 

There are many ways to make Micol Advanced BASIC programs stand alone. This 
chapter will explore all the possibilities. Pay special attention if you intend to use your 
programs outside of the normal Micol Advanced BASIC programming environment. 

Creating a Startup Disk for Launchable Programs 

lb create a system disk which you may use with the programs created with Micol 
Advanced BASIC, take the following steps (you may use any suitable GS/OS or ProDOS 

8 copy utility (the Finder or Copy 11 Plus wiU do just fiine): 

1, Make an exact copy of the Mkol Advanced BASIC System Disk (the disk labeled 
Master Disk). You may change the name of this copied disk, if you wish, 

2, From this new copied disk, in folder MicoLAdv^ASICA remove the files 
COMPILEILSHELL, EDITOR, AutoExec and the UTILITY folder. This 
should only leave the files MicoLAdv.BASlC and LIBRARY remaining. 

3. Move the Finder to this new disk: 

a) Delete the file named START under folder SYSTEM/ of the new disk 

b) Copy the file Finder from the MAB.SUPPORT disk (under the SYSTEM/ 
folder) to the SYSTEM/ folder of the new disk 

c) On the new disk, rename file Finder to Start. 

4. LocL Jie files and label your disk with an appropriate name. You should also 
include the version number ot Micol Advanced BASIC you are using, as well as 
the version number of the operating system. 

Now, if you boot this new system disk, you may directly launch your Micol Advanced 
BASIC programs by double cHcking them with the Finder, Note, that such a disk rannot 
be booted for program development, as the Loader will be searching for the non-existant 
files COMPILEILSHELL and EDITOR in the MicoLAdv.BASlC folder. 

Hard Disks and Launchable Programs 

A normal Micol Advanced BASIC program may be easily launched directly from a 
hard disk using the Finder and need not be converted to a GS/OS application. 

What is required to launch Micol Advanced BASIC programs from the Finder are: 
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1. A folder called MicoLAdv.BASIC directly under the bc»t volume. The boot volume 
is the volume that the operating system, GS/OS, was taken &x)m when your 
computer was started up (this is probably your hard drive). 

2. The files MicoljVdvJBASIC and LIBRARY taken from the MicoLAdv^BASIC 
folder of the disk labeled Master Disk. These files must reside in the folder 
MicoLAdv^BASIC described in 1. 

3. The file MicoUcon fix>m the Icons folder fix>m the disk labeled Master Diak This 
file must reside in the Icons folder of the boot volume. 

Now if, after booting, you were to double click a Micol Advanced BASIC program 
icon fi-om the Finder, the Micol Loader will load and begin execution of the separate run 
time Library and BASIC prograni as if they were a merged application file* 



IMPORTANT 



Utilizing the method described here as opposed to 
creating S16 files described below, has the ro^or 
advantage of keeping your compiled programs small and 
can save a great amount of valuable disk space and speed 
loading time. The method described here is the 
recommended method for creating laimchable programs. 



Stand Alone Micol Advanced BASIC Programs 

A Micol Advanced BASIC program which is completely self-sufficient (converted to a 
TumKey system, an Sl6 application or a CDA) is written just like any other program. 
The one rule you must follow is that the Micol Advanced BASIC program must be 
thoroughly debugged before you make the conversion. This is because the Micol 
Advanced BASIC Programming Environment is designed for program debugging, and 
stand alone apphcations are not. If a bug should appear in a stand alone application^ 
you will have to return to the programming environment to locate the problem. 

How Micol Advanced BASIC Boots 



In order for you to better understand what is required to create a stand alone 
application, we will describe what happens when you boot Micol Advanced BASIC from 
disk. 

Contained under the SYSTEM folder on the booting volume is the Micol Advanced 
BASIC loader named START. After the operating system (GS/OS) has booted, START 
is the first file executed During its execution, START searches first for the run time 
Library (file LIBRARY) located in a folder called MicoLAdvJBASIC under the boot 
volume. If this search is unsuccessful, it begins the same search, but this time on the 
same volume and directory as START is located If this search fails, it searches outer 
directories until it locates LIBRARY in any folder, or the search fails. 

Once LIBRARY is found, the folder in which LIBRARY resides is set as the system 
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folder from which all subsequent system access is done. 

If a file called lVnCOL,SYSTEM is detected of type MAB ($F2), it is assumed the 
disk is a turnkey disk, and attempts to load the run time library and load and execute 
the file MICOL^YSTEM. 

If the file MICOL.SYSTEM is not detected, it is assumed the system is intended for 
program development, and the files COMPILEILSHELL, EDITOR and LIBRARY are 

loaded, and you are placed into the programming environment. 

If all of these tests fail, the file START issues an error message and gives up. 

The file MicoLAdv^BASIC contained xmder the folder MicoLAdv^BASIC/ on the 
Master Disk is identical to the fiile START just described- This file is intended for 
launching Micol Advanced BASIC programs directly from a program launcher. This 
process was described earlier in this chapter* 

Creating a TumKey System 

A TumKey system is simply a program that automatically executes when the disk on 
which it resides is booted. The normal GrS/OS system disk is actually a TumKey system 
for the Finder, as the Finder is automatically executed after GS/OS has booted You wiU 
be creating a similar system, but for a Micol Advanced BASIC program. 

To create a TumKey system, take the following steps (you may use any suitable 
GS/OS or ProDOS 8 copy utility such as the Finder or Copy 11 Plus): 

1. Make an exact copy of the Micol Advanced BASIC System Disk (the disk labeled 
Master Disk). You may change the name of this copied disk if you wish. 

2. From this new copied disk, in folder MicoLAdvJBASIC/, remove the files 
COMPLLER^SHELL, EDITOR, MicoLAdv^ASIC, AutoExec and the 

UTILITY folder. This should only leave the file LIBRARY remaining in this 
folder. 

3» Copy the Micol Advanced BASIC program you wish to be automatically executed to 
the folder MicoLAdvJBASIC/ on this new disk, 

4, Rename this Micol Advanced BASIC program to MICOL.SYSTEM. 

5, Copy all files required by your Micol Advanced BASIC program to this new disk. 

Now, whenever this disk is booted, your Micol Advanced BASIC program will 
automatically load and execute. 

Creating GS/OS Applications 

There is a utility on the MAB.SUPPORT disk in folder MAB.T0.S16/ which you may 
use to make the conversion from a normal Micol Advanced BASIC program to an Sl6 
GS/OS appKcation file. This utility is called MAKE.SA. Also in the same folder is a 
special version of the run time Library, file LIBRARYS A which will be merged with 
your program to make the S16 application. 
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NOTE 



The S16 files created with the method described here are 
much larger than the normal Micol Advanced BASIC 
compiled programs. This means they occupy much more 
memory on disk, and require more time to load. In earlier 
versions of Micol Advanced BASIC, it was not possible to 
launch programs directly firom a program launcher* This 
is the main reason the method described here was 
devised. Unless you have some pressing reason for 
having a single, self-contained application on disk, we 
recommend you keep your Micol Advanced BASIC 
programs in the normal format and follow the rules on 
making yoxxr programs launchable described above. 



Take the foUowing steps to create your independent Si 6 appUcation: 

1, Start Micol Advanced BASIC. 

2, Once the command shell prompt appears, insert the disk labeled MAB,SUPPORT 
iato a suitable drive, 

3, Using the PREFIX command, set the default prefix to 
/MAB,SUPPORT/lVIAB,TO.S16. 

4, Enter RUN MAKE^A followed by a carriage return (remember the system will 
append the •LNK extension automatically), 

5, FoUow the instruction which appear on the screen. You will receive detailed 
instructions what to do next Briefly, two inputs are required; the Pathname of 
the file to be converted (complete with extension, if any) and the Pathname the 
converted file will have. 



NOTE 



By specifying the fiiU Pathname each time, you may 
convert any MAB file on the system, and have this file 
written to any volume anywhere within the system. 



NOTE 



If you include files MAKE.SA and LIBRARYSA, just 
described, inside the UTILITY folder under the Micol 
Advanced BASIC system folder, you may create SI 6 
applications by simply entering MAKE,SA<CR> fix)m the 
Command Shell. This method is only suitable if you have 
a hard drive. 
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Creating Classic Desk Accessories 

Micol Advanced BASIC supports two types of CDAs> Primary CDAs and Secondary 
CDAs, 

Contained on the MAB.SUPPORT disk, under folder MAB.TO.CDA, is a utility for 
converting your MAB programs to CDAs. Also under this folder are two versions of the 
run time Library designed for creating CDAs: UBRARYXDA is intended for merging 
with your MAB programs to create Primary CDAs, and a dummy run time Library, 
LTBRARY.SML, intended for creating Secondary CDAs. 

All systems that contain CDAs written under Micol Advanced BASIC must have qq^ 
Primary CDA. This is because the Primary CDA contains the full run time Library 
which all CDAs, including Secondary CDAs, will use. For this reason, yoxir first CDA 
must be a Primary CDA, and all other CDAs must be Secondary. Secondary CDAs are 
little more than a MAB file converted to CDA type files. 



WARNING 



The Primary CDA must always be executed first. This is 
because there are pointers that must be set for the 
Secondary CDAs to use. If you attempt to access a 
Secondary CDA without first having executed a Primary 
CDA, the computer will probably crash. 



In order to convert a MAB file to a CDA, take the following steps: 

1. Boot Micol Advanced BASIC. 

2. Insert the disk labeled MAB,SUPPORT into any suitable drive. 

3. At the SheU monitor, enter PREFIX /MAB.SUPPORT/MARTO,CDA/<CR>, 

4. Enter RUN MAKE,CDA<CR>. 

5. Follow the detailed instructions that appear on the screen. This utility functions 
essentially the same as the MAKE.SA utility described above. 

Once the conversion is completed, copy the CDAs to the folder 
SYSTEM/DESKACCS/ on the boot volume. The next time this disk is booted, these 
CDAs will appear m the control panel of yoxir Apple IIGS, 
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Chapter Six 

Converting Applesoft Programs 
Overview 

Micol Advanced BASIC is a language system that is based on Applesoft BASIC. This 
means> that when Micol Advanced BASIC was first being developed, Applesoft was 
taken as the root language. Structured capabilities and the ability to access the power of 
the Apple IIGS were added to make what is now Micol Advanced BASIC for the Apple 
IIGS. 

What this means to you is that, with a Httle work, you should be able to use your 
Applesoft programs under Micol Advanced BASIC. 

It is the purpose of this chapter to explain most of the modifications you will have to 
perform ia order to compile your Applesoft programs as Micol Advanced BASIC 
programs. 

Source File Conversion 

Applesoft files are essentially tokenized text files. Whenever you entered an 
Applesoft line of code and pressed Return, you probably noticed a shght delay before the 
cursor returned. This delay was caused by the Applesoft interpreter tokenizing this line 
of code. This means the Applesoft reserved words were converted into numeric 
equivalents, pointers to the next line were established and line numbers were converted 
into binary. This was done to speed the execution of the Applesoft program. If you think 
Applesoft is slow, think how slow it would be if these lines had not been tokenized. 

The first task you will have to perform is to convert these Applesoft source files into 
text files which Micol Advanced BASIC can use. Don't worry, this task has been largely 
automated, so all you have to do is foUow a few steps. 

There is a file on the MAB.SUPPORT disk, under the volume directory, called 
CONVERT designed lo convert your Applesoft programs to text files. Simply take the 
following steps: 

1. Boot any ProDOS 8 System Disk. This will probably be the disk you used when you 
were originally developing your Applesoft programs. 

2. Load the Applesoft program you want to convert iato memory. This program must 
not have a line number less than twenty. 

3. Insert the MAB. SUPPORT disk into any smtable drive. 

4. Enter EXEC /MAB.SUPPORT/CONVERT<CR>. 

5. Enter RUN<CR>. Your Applesoft program will be converted into a text file, 

6. Enter SAVE <Pathname><CR> where Pathname will be the source filename of this 
text file. 

7. Boot Micol Advanced BASIC and get into the Ttext Editor. 

Part Six: Program Management 



240 Chapter Six: Converting Applesoft Programs 



8. Load this converted text file into the Micol Advanced BASIC source code Editor. 

You are now in a position to make the changes required to compile this file. 
Unfortunately, your first task will be to remove the leading spaces in each Hne generated 

by the file conversion. 

General Conversion Rules 

Following is a list of things to look out for when modifying a converted Applesoft 
program into a Micol Advanced BASIC program. Although this Ust is as complete as 
possible, we unfortimately cannot foarsee every circumstance. Some problems probably 
wiU require a good knowledge of Micol Advanced BASIC. 

DEVI Statements 

Applesoft allows DIM statements anywhere in a program and the dimensioning may 
be done with variables. Micol Advanced BASIC requires the DIM statements to be at 
the top of the program, and only integer Literals are accepted as parameters. 

DATA Statements 

DATA statements must be at the top of the program^ they cannot reside anywhere as 
in Applesoft. The following rules also apply with DATA statements: 

1, Quotation marks must be around string literals, for example "This is a string^. 

2, Values read into real variables must be expressly specified as reals. For example, 
22 must be written as 22,0. 

3, No empty entries such as „ are allowed 

Strings 

If you are forcing a string garbage collection with a PRINT CHR$(4); *TRE (0)'', 
simply remove it Our garbage collector is far faster anyway. 

String functions such as LEFTS and MID$ check for overflow errors which Applesoft 
does not do. You may have to check the string lengths before making these calls. 

Slot Input/Output 

Replace IN# and PR# with INSLOT and OUTSLOT respectively. Refer to the 

appropriate sections in this manual to understand the use of these commands^ 
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Turning the Printer On and Off 

Turn the printer on with a PRTON instead of PR#1. Yoxir printer must be in slot 
one, however. 

Turn the printer off and the screen on with a TEXT. 

PRINTing 

Unlike the PRINT statement in Applesoft, semi-colons are required and cannot be 
impUed, The statement PRINT "Yoxir name is " N$ may be rewritten as PRINT 
**Yaur name is ^; Naine$ 

FLASH Command 

FLASH is not supported. Replace FLASH with INVERSE. 

Cursor Positioning 

HTAB and VTAB require parentheses around the parameter. SPC, TAB, and PCS 
must have a semi-colon following the parameter to hinder a carriage retnm. 

Control of Flow 

1, IF <:Real Variable> THEN is not allowed Only boolean variables may be so used 
You may replace this statement with IF <Real Variable> > THEN. 

2, IF Relop GOTO is not allowed An IF statement requires a THEN. 

3, NEXT without its corresponding variable is not allowed You will have to exphcitly 
specify this variable, 

4, Statements Uke NEXT X, Y are not allowed These should be rewritten NEXT X: 
NEXTY. 

5, FOR loops behave a little differently than they do under Applesoft, If you are 
having trouble with your FOR loops, check the FOR loop rules described in this 
manual. 

High Resolution Graphics 

Under Applesoft, High Resolution graphics only has a resolution of 280 by 192. 
Under Micol Advanced BASIC, although the Super High Resolution graphics commands 
are the same as Applesoft's High Resolution graphics commands, the resolution is much 

higher 

Under Micol Advanced BASICs Super High Resolution graphics, the resolution is 
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either 320 by 200 (for HGR) or 640 by 200 (for HGR2). You will have to modify the High 
Resolution graphics coordinates in your Applesoft programs accordingly. 

Also, the colors you set using the COLOR command are different; Micol Advanced 
BASIC has far superior colors to Applesoft, You will have to determine the best colors for 
your graphics and redefine them. 

Shape Tables are not supported. You will have to create these shapes using the 
Functions described in Chapter Ten, Part Three of this manxial, 

PEEKS and POKEs 

Some of the addresses you may have referenced in your Applesoft program with 
PEEKs and POKEs may be different under Micol Advanced BASIC. In particular, pay 
attention to addresses in zero page, that is, addresses betweeen and 255, 

Check Appendix A in this manuals Appendix A is the memory map for Micol 
Advanced BASIC. This should tell you which locations need to be modified. Note that 
some locations have no equivalent. 

Functions 

Any DEF FN lines may be converted to multi-hne functions using the 
FUNC^ENDFUNC construct 

Disk Filing 

Filing commands are the most complicated to modify. Unfortunately, these lines will 
have to be rewritten. Here are some thing to note: 

PRINT CHR$ (4); has no affect on the operating system under Micol Advanced 
BASIC 

• Setting a new default prefix is PREFIX "String** or PREFIX Svar 

• Getting the default prefix is Volume_Name$ = PREFIX$ 

• You wiQ have to use CAT$ to get a catalog 

The following tables should help you make additional filing conversions: 

Sequential Access Commands 

Reading a File 

Applesoft Micol Advanced BASIC 

"OPEN A^OKNAME/PILEJ^AME" ROPEN (1) WOL.NAME/FILE J^AME" 

TIEAD VOKNAME/FILE JNTAME" 
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^TSTPUT L$" INPUT (1) Liiie$ 

CLOSE VOL.NAME/FILE.NAME" CLOSE (1) 

ONERR GOTO <Lme Nimiber> IF EOF (1) THEN <Stms> 



«- 



Writing a File 
Applesoft Micol Advanced BASIC 

*^OPEN/VOUNAME/FILEJ^AME" 
"DELETE VOL^NAME/FILE^NAME" 

"OPEN VOL.NAME/PILE J^AME'' WOPEN (1 ) "VOL.NAME/FILE,NAME" 
"WRITE ATOUNAME/FILEJNAME" 

"PRINT L$ PRINT (1) Line$ 

CLOSE A^OL.NAME/FILE JTAME" CLOSE (1) 



", 



If you are using random access files in your program, then you wiH have to learn the 
use of the SEEK command in Micol Advanced BASIC. Its usage is too complicated to 
explain here. 

Note that the PRINT CHR$ (4); statement in the above tables has been removed 
from the Applesoft lines for resisons of space, 

Go for It 

Now that you have made the conversion, the fun can begin. Start using Micol 
Advanced BASIC as more than just an Applesoft compiler. 

The first thing you will probably want to do is speed up your programs. If practical, 
convert the real variables into integers. You may want to use the Compiler Directive 
INT (A-Z) to force all reals to integers; then> in your program^ you may selectivly convert 
some of these integers into reals with the "*&" character 

Add structure to your programs, Make yoinr arrays larger. Use extended arithmetic, 
Etc. Etc Now, get your money's worth out of Micol Advanced BASIC. 
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Appendices 

Appendix A 

Memory Usage 

Because all of Micol Advanced BASIOs system files are relocatable, we cannot tell 
you where the Compiler, Editor and run time Library reside in memory. These locations 
will vary according to the conditions xinder which they were loaded. Besides, there is 
probably no time that you will need to know these locations as the files generated by the 
Linker are also relocatable load files and will load in the locations the system says are 
free. 

Note the distinction between Direct Page locations for the run tune Library given 
here, and Zero Page locations used by Applesoft. There is no relationship between the 
two. Because of system requirements, we could not make any locations the same, so all 
PEEKs and POKEs to Zero Page tmder Applesoft will have to be modified- Some 

locations in Applesoft will have no comparable locations in Micol Advanced BASIC, 



Location Usage 

$5C, Absolute long jump constant 

1-2 COUT vector, absolute address 

3 COUT bank vector, part of bytes 1-2 

4-5 Max. characters allowed for INPUT 

6-15 Temporary storage 

16-17 Temporary string usage 

18-19 Long Integer flag 

20-23 Temporary storage 

24-25 Library routine n' aber 

26-27 Free locations 

28-31 Variable one relative location 

32-35 Variable two relative location 

36-39 Variable three relative location 

40-41 Integer random number 

42-43 WAVE and INSTRUM buffer counter 

44-45 Left border of text screen 

46-47 Right border of text screen 

48-55 Misc, usage 

56-59 Pointer to DATA storage 

60-73 Misc. usage 



Comment 

Don't Modify 

LSB, MSB order, restore if modified 

3 bytes together for long address jump 

Default of 255 

Don't modify 

Frequent usage 

Don't Modify 

ML usage okay 

Set by Linker, don't modify 

ML usage okay 

Don't Modify 

Don't Modify 

Don't Modify 

Don't Modify 

See WAVE & INSTRUM 

Modify to shrink text screen 

Modify to shrink text screen 

Don't modify 

Don't Modify 

Don't modify 
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Location Usage 

74 Back space flag 

76-95 Misc. usage 

96-99 Fast file buffer pomter 

100- 10 1 Bottom of text screen 

102-103 Tbp of text screen 

104-115 Misc. usage 

116-117 Horizontal position of cursor 

118-119 Vertical position of cursor 

120-127 Screen output \isage 

128-129 PRINT USING usage 

130-131 PRINT USING misc. usage 

132-135 Misc. usage 

136-143 Internal string usage 

144-146 Cursor character, default inverse space 

146-147 Output character mask (default 255) 

148-151 ^^deo memory 

152-153 Internal stack counter 

154 library error code storage 

155 GS/OS error code storage 
15&-157 Extended real storage flag 
158-161 Actual address of first variable 
162-165 Actual address of second variable 
166-169 Actual address of third variable 
170-173 Start of DATA storage 
174-177 Last byte of DATA storage 
178-181 Start of string storage 
182-185 End of string storage 

186-187 SPEED setting 

188-189 TRACE flag 

190-193 ONERR GOTO address 

194-197 RESUME address 

198 PRINT USING "," character 

199 PRINT USING "$" character 

200 PRINT USING "." character 
202 True Value 

204-205 Line number where error occurred 

226-239 Misc. uses 



Comment 

Delete mode flag for INPUT 

ML usage okay 

Don't Modify 

Modify to shrink screen 

Modify to shrink screen 

MLusage okay 

Best not to modify 

Best not to modify 

Don't Modify 

Don't Modify 

Don't Modify 

ML usage okay 

Don't Modify 

Modify for another screen cursor 

Modify will change output char. 

Don't Modify 

Don't Modify 

Needed in error trapping 

Needed in error trapping 

Don't Modify 

Don't Modify 

Don't Modify 

Don't Modify 

Don't Modify 

Don't Modify 

Don't Modify 

Don't Modify 

Set by SPEED, don't Modify 

Set by TRACE, don't Modify 

Don't Modify 

Zero if no ERROR comp. option 

Modify as required 

Modify as required 

Modify as required 

Many uses 

Useful in error trapping 

Don't Modify 
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Location Usage Comment 

240-255 System usage Protected, POKEs cannot modify 

Other Memory Usage 

$E100EC-$E100EF Secondary CDAjump location 

$E100F0-$E100F3 Jump location to Run Time library 

$E100F4-$E100F7 Jimip location to integrated Compiler/Shell 

$E100P8-$E100FB Jump location to Tfext Editor 
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Appendix B 
Screen Output 



Micol Advanced BASIC has its own super fast screen output routines, as you 
probably already have discovered The screen output, however, functions very much as 
the screen output on older Apple lis in that certain control codes perform certain actions, 
and certain memory locations control certain features. We wiU describe these briefly 
here. 

Use PRINT CHR$ (Value); to perform the stated action: 

Value Action 



8 

10 

11 

13 

14 

15 

21 

22 

23 

29 

64-95 



Move cursor left one position 

Move cursor down one hne, scroll if necessary 

Move cursor up one Hne, scroll if necessary 

Carriage return 

Set noiTQal text mode 

Set inverse text mode 

Move cursor right one position 

ScroU screen down one Une 

ScroU screen up one line 

Clear to end of line 

MouseText characters; issue MS^TEXT first 



Important Direct Page Locatioxis 
Location Function 

44 Left border of text screen, default is 1. 

46 Right border of text screen, default is 80 

100 Vi<^"^^ '^*°P border of text screen, default is 1 

102 Bottom border of text screen, default is 24 

116 Current horizontal cursor position 

118 Current vertical cursor position 

144 Cursor character, default is 32, inverse space 

146 AND mask for character output, default is 255 

The above direct page locations may be modified (POKEd) to alter the text screen 
display. But be careful! Incorrect values may cause a system crash. For example, if you 
wish to create text windows, you may shrink the text screen by changing locations 44, 
46, 100 and 102. Be certain the values are vahd, and the cursor is within the new text 
screen before PRINTing. 



Appendices 



Appendix C: Run Time Error Codes 



248 



Appendix C 



Run Time Error Codes 



Whenever a run time error occurs, the error code is placed into one of two locations in 
the run time libraiys Direct Page which may be accessed by a user's program. 

If the error is generated within the run time Library itself, the error code is placed 
into location 154 and location 156 is zero. If the error was generated by the operating 
system, location 155 will contain the error code, and location 154 will be zero. 

Each code is generated by a unique error situation which causes a unique message to 
be printed, if ONERR GOTO is not active. The run time Library's error codes are listed 
below, in this appendix, while GS/OS's error codes are Hsted in Appendix D. 

You may disable an active ONERR GOTO by POKEing zeroes into locations 191 
and 192. Note that both locations must contain zeroes for ONERR to be disabled. 



Code Message output to screen 

1 Error in exponentiation 

2 RETURN without GOSUB 

3 RESUME without ERROR option 

4 End of data 

5 Bad subscript error 

6 Illegal value in fimction 

7 niegal POKE value 

8 Overflow in addition operation 

9 Return stack error 

10 Comma tab error 

11 EXP error 

12 Out of string data 

13 Overflow in TAB 

14 Division by zero error 

15 Overflow in subtraction 

16 String function overflow 

17 Overflow in concatenation 

18 Elegal string assignment attempted 

19 String overflow error 

20 Applesoft graphics error 

21 Illegal real literal error 

22 FOR variable overflow 

23 Overflow in multiplication 



Comment 

Integer '^' range exceeded 

Perhaps GOTO instead of GOSUB 

Need ERROR compiler option 

No more DATA to READ 

Array limit exceeded 

Probable bad math function parameter 

Value > 255 or bad address 

Integer addition range exceeded 

Obo many RETURNS for GOSUBs 

Implied tabs overflowed before <CR> 

EXP function exceeded limits 

DATA is not of string type 

TAB paramet. . is negative or > 80 

Integer division by zero 

Integer subtraction result < -32767 

Attempt to create string > 1023 chars. 

Same as 16 

General string error 

General graphics error message 
String cannot be converted to real 
Integer FOR counter out of range 
Integer multiphcation out of range 
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Code Message output to screen 



24 


String overflow 


25 


FOR loop underflow 


26 


Negative square root attempted 


27 


Illegal PDL value 


28 


niegal SPEED value 


29 


Insufficient string space reclaimed 


30 


String access to unassigned variable 


31 


File output error 


32 


Attempt to read past EOF 


33 


Invalid pathname in filename 


34 


Dimension and array use mismatch 


35 


Mismatch in parameter type 


36 


Assign in ADDRESS mismatch 


37 


Specified value > 255 for SPC 


38 


Maximum of 255 matches in UNDlilX 


39 


Time or date error 


40 


READ data mismatch 


41 


Invalid floating point operation 


42 


Floating point underflow 


43 


Floating point overflow 


44 


Floating point division by zero 


45 


Floating point inexact conversion 


46 


Floating point error 


47 


Undefined segment call 


48 


Stack underflow 


49 


No direct page memory for graphic 


50 


Quick Draw II startup error 


51 


Illegal tool number 


52 


niegal function number 


53 


Unable to start up sound 


54 


Music or Noise startup error 


55 


limit seven items off stack 


56 


No direct page memory for sound 


57 


Cannot start Noise Synthesizer tool 


58 


Music or Noise error 



Comment 

Maximiim of 1023 characters in string 
FOR loop stack problem 

Only 1, 2, 3 or 4 allowed 
Attempt to set SPEED > 255 
Use BANKJ^TO compiler option 
String var. in shaping fiinction not set 
Probable SEEK error. No data at point 
Read past last write, or SEEK error 
Probable unassigned string variable 
Number of dimensions mismatch 
Procedure and call parameters wrong 
Probable parameter corruption, rare 
Only through 255 allowed in SPC 
INDEX position parameter > 255 
System error 

READ attempt to other type 
General floating point error 
Try using EXTEND compiler option 
Try using EXTEND compiler option 

Cannot convert real to string 
General floating point error 
No SEGMENT number for CALL 
Perhaps bad recursion attempted 
Bank zero memory used up 
Cannot start High Resolution Tool 
TOOLBOX accepts only Tool # < 256 
TOOLBOX accepts only Func. # < 256 
Cannot startup IboKs) for Noise/Music 
Similiar to 53 

Tbo many pull variables in TOOLBOX 
Bank zero memory used up 
System error in NOISE command 
Sound system error 



Appendix C: Run Time Error Codes 



250 



Code Message output to screen 

59 Parameter stack overflow 

60 FuQCtion stack ove3rflow 

61 String buffer allocation 

62 File buffer allocation error 

63 INPUT length out of range 

64 FUNCtion retura incompatable type 

65 System memory error 

66 Undefined library routine 

67 Cannot RUN program or application 

68 No HGR/HGR2 issued for DESKTOP 

69 Cannot start Dialog Tbol 

70 Cannot start Event Manager 

71 No direct Page for Event Manager 

72 Cannot start Window Manager 

73 Cannot draw Dialog Box 

74 No direct page for Control Manager 

75 Maximum of 16 items for Dialog Box 

76 Cannot start Control Manager 

77 Cannot start up Line Editor 

78 Item error 

79 Unable to create W^dow 

80 Unable to close Window 

81 Mouse Control error 

82 Unable to startup Menu 

83 Mouse control without Desktop 

84 Cannr ' start Scrap Manager 

85 Only class one calls supported 



Comment 

Cannot store more function parameters 

Too many unresolved FN calls 

Probably BANKING set too large 

Not enough memory to read files 

POKE to location 5 > 3 

FN call to wrong fonction type 

Fatal error condition 

Bad compiler code generation (call us) 

Bad RUN command issued 

Must set graphics mode for Desktop 

Fatal Desktop system error 

Fatal Desktop system error 

Bank zero memory used up 

Fatal Desktop system error 

Desktop system error 

Bank zero memory used up 

Too many parts in DIALOG 

Fatal Desktop system error 

Fatal Desktop system error 

Part bad in DIALOG 

Desktop system error 

Desktop system error 

Desktop system error 

Error in MENU 

MOUSE needs Desktop command 

Desktop system error 

Probable GS/OS call number < $2000 
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Appendix D 
GS/OS Error Codes 

As mentioned in the previous Appendix, whenever GS/OS signals an error, that error 
is placed into location 155 and location 154 is zero. On some rare instances, the library 
routine may have trapped the error first, 

Decitnal EjTor Code Message sent to screen 

1 Invalid GS/OS call number 

7 GS/OS is bxisy 

16 Device not foxind 

17 Invalid device request 

32 Invalid request 

33 Invalid control or status code 

34 Bad call parameter 

35 Character device hot open 

36 Character device already open 

37 Interrupt vector table full 

38 Resource not available 

39 Input/output error 

40 No device connected 

41 Driver is busy 

42 Error not defined 

43 Write protected 

44 InvaHd byte coimt 

45 InvaHd block address 

46 Disk switched 

47 Device not online 

64 InvaHd pathname or device name syntax 

67 InvaHd file reference number 

68 Subdirectory not found 

69 Volume not found 

70 File not found 

71 DupHcate pathname 

72 Volume full 

73 Volume directory full 
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Decimal Error Code Message sent to screen 

74 Version error 

75 Unsupported storage type 

76 End of file encountered (out of data) 

77 Position out of range 

78 Access not allowed 

79 Buffer too small 

80 File is open 

81 Directory structure damaged 

82 Unsupported volume type 

83 Parameter out of range 

84 Out of memory 

87 Duplicate volimie name 

88 Not a block device 

89 Invalid level 

90 Block number out of range 

91 Illegal pathname change 

92 Not an executable file 

93 Operating system/file system not available 

95 Return stack overflow 

96 Data unavailable 

97 End of directory 

98 Invalid FST call 

99 Missing Resource 

100 InvaUdFSTID 

127 Illegal numeric value in file 

All the error codes and messages but the last are standard GS/OS errors. The last is 
a special Micol error code. 
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Appendix E 
Compiler Reserved Words 

The following words have a special meaning and may not be used for any other 
purpose then they were intended. In particular, they may not be used as Program, 
variable. Function, Procedure or Routine names. 

ABS, ADDR, ADDRESS, ALIAS, AND, APPEND, ASC, AT, ATN 

BEGIN, BELIEVE, BELL, BKCOLOK, BLOAD, BSAVE, BYE 

CALL, CASE.OF, CAT$, CHAIN, CHR$, CLEAR, CLOSE, 
COPY, COLOR, COS, CREATE 

DATA, DATE$, DELAY, DRAWSTR, DECLARE, DELETE, 
DIALOG, DIM, DISPLAY, DO, DOUBT, DUNNO 

ELSE, ELSE_DO, END, ENDCASE, ENDDO, ENDFUNC, ENDIF, 
ENDPROC, EOF, EXP 

FALSE, FILE, FLUSH, FOR, FORMAT, FN, FRE, FREEMEM, FUNC 

GET, GET.MEM, GOSUB, GOTO, GR, GS_OS 

HCOLOR, HGR, HGR2, HUN, HPLOT, HOME, HTAB 

IF, INCLUDE, INDEX, INKEY$, INPUT, INSERTS, INSLOT, 
mSTRUM, INT, INVERSE 

LEFT$, LEN, LET, LINK, LOCK, LOG, LOWER$, LRETURN 

MENU, MrD$, MOD, MOUSE, MOV.MEM, MS_TEXT, MUSIC 

NEXT, NOISE, NORMAL, NOT, NOTRACE, NOTICE 

OPEN, ON, ONERR, ONLINE$, OR, OUTSLOT 
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PDL, PEEK, PERFORM, PLOT, POKE, POP, POS, PREFIX, 
PREFIX$, PRENT, PRTON, PROC 

QUIET 

READ, REM, RENAME, REPEAT, RESUME, RESTORE, RETURN, 
RIGHT$, RND, ROPEN, ROUND, ROUTINE, RUN 

SCRN, SEEK, SEGMENT, SON, SILENCE, SIN, SQR, SPC, 
SPEED, STEP, STOP, STRACE, STR$ 

TAB, TAN, TEXT, THEN, TIME$, TO, TOOLBOX, TRACE, TRUE 

UNTIL, UNLOCK, UPPER$, USING 

VAL, VALUE, VLIN, VTAB 

WARNING, WAVE, WEND, WHILE, WINDOW, WOPEN 

Note: compiler options are not reserved words within a program. 
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ASCII Character Codes 



The following is the table of the ASCII (American Standard Code for Information 
Interchange) codes supported by Micol Advanced BASIC. You may use the ASC and 
CHR$ functions to go between the code and the character representation. 



Value 



Character 



Value 



Character 






NUL 


29 


GS 


1 


SOH 


30 


RS 


2 


STX 


31 


US 


3 


ETX 


32 


(Space) 


4 


EOT 


33 


! 


5 


ENQ 


34 


II 


6 


ACK 


35 


# 


7 


BEL(BeU) 


36 


$ 


8 


BS (Left Arrow) 


37 


% 


9 


HT(l^b) 


38 


& 


10 


LF (Lme Feed) 


39 


t 


11 


VT (Up Arrow) 


40 


( 


12 


FF (Form Feed) 


41 


) 


13 


CR (Carriage Return) 


42 


* 


14 


SO 


43 


+ 


15 


SI 


44 


7 


16 


DT<E 


45 


- 


17 


GDI 


46 


, 


18 


DC2 


47 


/ 


19 


DCS 


48 





20 


DC4 


49 


1 


21 


NAK (Left Arrow) 


50 


2 


22 


SYN 


51 


3 


23 


E'l'B 


52 


4 


24 


CAN 


53 


5 


25 


EM 


54 


6 


26 


SUB 


56 


7 


27 


ESC (Escape) 


56 


8 


28 


FS 


57 


9 
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Value Character Value Character 

58 : 93 ] 

59 ; 94 ^ 

60 < 95 _ 

61 = 96 ' 

62 > 97 a 

63 ? 98 b 

64 @ 99 c 

65 A 100 d 

66 B 101 e 

67 C 102 f 

68 D 103 g 

69 E 104 h 

70 F 105 i 

71 G 106 j 

72 H 107 k 

73 I 108 1 

74 J 109 m 

75 K 110 n 

76 L 111 o 

77 M 112 p 

78 N 113 q 

79 O 114 r 

80 P 115 8 

81 Q 116 t 

82 R 117 u 

83 S 118 V 

84 T 119 w 

85 U 120 X 

86 V 121 y 

87 W 122 z 

88 X 123 { 

89 Y 124 I 

90 2 125 ) 

91 [ 126 

92 \ 127 DEL (Delete) 
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6502 addressing format 
6502 microprocessor 
65C02 microprocessor 



65816 microprocessor 



Alphaniimeric 
ASCn code 

Assembler 

Assembly code 
Assembly language 



Batch processing 

Binary code 
Binary files 
BIT 

Byte 
Chaining 



Two byte addresses specified in least significant byte, most 
significant byte order, 

CPU used in the Apple 11+ and early models of the Apple 
lie. 

CPU used in the enhanced Apple He and Apple He. 
Software written for the 6502 will run on it. This chip has 
27 additional machine language instructions, 

CPU used by the Apple IIGS and Apple lie upgraded GS. 
Most software written for the 6502 and 65C02 wiU run on 
it. It is more than just a 16 bit version of the 6502 since it 
has many more instructions and can acess as many as 16 
million bytes of memory. 

Usually used to describe characters which consist of letters 
of the alphabet and digits. 

The acronjrm of American Standard Code for Information 
Interchange, A standardized code used to represent letters, 
digits and punctuation symbols. The capital letter A is 65 
(decimal) in ASCII code. 

A program which can take as input an assembly language 
text file and translate it into the binary code the computer 
can execute, 

A formatted text file an assembler can translate into binary 
code. 

The lowest level of the programming languages, specific to 
a given microprocessor. AL uses short mnemonics 
corresponding directly to machine instructions and allows a 
programmer to use symbolic codes. At this level, the 
programmer is programming the CPU, 

Allows the system to take its commands fi-om a file on disk 
rather then the keyboard. Under Micol Advanced BASIC, 
the BATCH command creates a batch process. 

The same as machine code. 

Machine language files saved to tape or disk. 

Acronym of Binary digiT The smallest imit of information 
in a computer. Has a value of zero or one. 

A collection of bits wired together. In almost all cases, a 
byte consists of 8 bits. A b3rte can represent a character, a 
number between and 255 or a machine instruction, 
among other things. 

The process of joining separate text files by the compiler. 
The compiler can successfiiUy compile separate text files, as 
though they were a whole program. 
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Compiler 



CPU 

Cursor 
Decimal 
Direct Page 



Editor 

Error condition 

Executable module 

Flag 

FUe 

Hexadecimal 
Integer 

Interpreter 



Library 



A program that converts a program, usually a text file 
written in a higher level language, into an intermediate 
code called an object module. A linker is then required to 
convert this object module into a machine usable file that 
can later be executed. 

Strands for Central Processing Unit, the "T^rain" of a 
computer When writing in machine language, you are 
programming the CPU. 

A special character, often blinking, used to show the user 
where on the screen he/she is entering characters, 

A numbering system based on the number 10; the 
numbering system we use in every day life. 

A special 256 bjrte area in memory bank zero which can be 
treated as a zero page by a program. Unlike zero page, 
which begins at location zero in bank zero, direct page is 
referenced by a special register for this pxu^se and can 
begin at any location in bank zero. This distinction 
between direct page and zero page is important because 
PEEKs and POKEs referencing addresses less than 256 
under Micol Advanced BASIC reference the run time 
Kbrarys direct page, and not zero page. 

Same as text editor, A program which allows the user to 
create, modify and save text files. 

The state of a program after it has detected an error during 
its execution. 

The binary code created by the linker, which is the actual 
code which will be executed- 

A boolean variable which can be set or imset, so that later a 
determination can be made based on its value. 

A collection of data stored in some memory device; this can 
be the computer's memory, disk or tape. On magnetic 
media, a file name is usually associated with the file. 

A number system based on the number 16 (base 16). 
Letters A through F are used to stand from 10 to 15, 

A variable type which has a limited range and no firactional 
part. Micol Advanced BASIC for the GS has two ranges of 
integers, short and long. Short integers have a range of 
±32767, while long integers have a range of ±2,147,483,647. 

A program which reads program code written in a 
high-level language one statement at a time, executes it> 
then goes to read the next instruction until the program 
terminates. Traditional BASIC language systems are 
interpreted Interpretera are remarkable for their 
convenience and lack of speed. 

Contains the nm time routines required by the executable 
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Linker 
Load 

MacMae code 
Memory location 

Micol Systems 

Mnemonic 

Modularization 

Octal 
Program 
Real number 



Reserved word 

Run time library 
Save 

String 
Structured design 



mod\ile at execution time. 

A program that converts the object module(s) created by the 
compiler into an executable load mod\ile» 

The act of bringing in information to the computer's 

memory from a long term storage device such as a disk 
drive- 
Almost synonymous with assembly code. Usually refers to 
the binary code which the computer directly executes. 

The same as a byte of memory. Can be thought of as an 
addressable little box in the computer containing a piece of 
information. 

A dynamic software house located in a suburb of Toronto, 
Canada, Dedicated to quality systems' software, MICOL is 
an acronym of Micro COmputer Languages. 

A collection of characters which can help you remember 
something. "^JMP", for example, can represent $4C ia 
machine code and is a mnemonic for it. 

The act of breaking a program into small, easily 
maintainable parts* While Uttle overhead is involved, it 
greatly minimizes program maintenance - 

A number system based on the number 8 (base 8). Octal 
was once used more than today A 10 in octal is decimal 8. 

A collection of instructions designed to perform (a) specific 
action(s). 

The same as floating point ninnber. A number which can 
contain a fractional part and has a large range. Under 
Micol Advanced BASIC there are two ranges of real 
numbers, normal and extended. Normal reals require two 
bytes of storage and have about seven digits of accuracy 
Extended reals require 10 bytes of storage and have about 
19 digits of accuracy. 

A, usually English, word whir' has a special meaning to 
the compiler and cannot be used as a variable name. 
GOSUB is an example of a reserved word in BASIC. 

See Library 

The act of storing all or part of a computer's memory to 
some long term storage device such as a disk, 

A collection of characters. The double quotation mark is 
used by the compiler to declare strings, e.g. *This is a 
string". 

A systematic approach to the creation of software by using 
a step-by-step procedure for solving the problem. It 
consists of a smooth program flow, modularization of code, 
meaningful identifiers, etc. 
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Two' complement value A number in which the negative value is achieved by 

adding one to the inverse bit pattern of the positive value. 
-1 is $FFFF in two's complement for short integers. 

Zero Page The area in memory between locations and 255 in bank 

zero. Do not confiise zero page with direct page which can 
be anywhere in bank zero. 
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Index 



! 62 

% 62 

& 63 

* 67 

+ 67,77 

- 67 

/ 67 

\ 47 

( 48 

) 48 

A 

ABS 72 

ADDR 163 

Aexpr 11 

Aliases 55 

Order 49 

Alop 11 

APPEND 109 

Apple ne/c 10 

Arithmetic operators ... .67 

Arrays 65 

Multi Dimensional . . .65 

Nesting 67 

Subscripts 67 

ASC 77 

ASCII .76-77 

Assembly language 232 

ATN 74 

AutoExec 5, 18 

B 

BANK_NO 50 

BASIC 12 

BASIC.SYSTEM 16 

Batch files 17 

BELIEVE 159 

BELL 222 

BKCOLOR 143 

BLOAD 164 



Booting MAB 235 

Branching 

Selective 119 

Unconditional 118-119 

BSAVE 165 

BYE 117 

c 

CALL 229-230 

Case statement 

Defining 87 

Case statements 

Nesting 88 

CASE_OF 87, 172 

CAT 18 

CAT$ 103 

Catalog 14, 18 

CHAIN 227 

CHR$ 78 

Classic Desk Accessories 2 
Classic Desk Accessories . 238 

CLEAR 71 

CLOSE 109 

CODE 50 

Code optimization .... 54 

CodeSmith 15 

COLOR 139 

Command Shell 1 

Command Shell 2 

Commercial license .... 44 

COMPILE 19,38 

Compiler 

Aborting compilation . 39 

Advantages 3 

ALIASES 55 

AND 68 

Arrays 69 

Chaining 227 

Code generation .... 41 

Comments 47 

Compiled listings . . . 40,58 
Control-C 39 
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Index 



Control-S ....... .40 

Directive defimtion . . .50 

Error messages 40 

Filing Commands , . , .103 

L 40 

Line continuation . . . .47 

Listiags 52, 54, 58 

Logical operators ... .68 

NOT 68 

Options 50 

OR 68 

P 40 

Precedence rules ... .68 

RAM disk usage 39 

Scratch files 39 

Statistical information .59 

Symbol Table 58 

Syntax errors 40 

Variables 61 

Compiler Commands 

ABS 72 

ADDR 163 

ADDRESS 130 

APPEND 109 

ASC 77 

ATN 74 

BELL 222 

BKCOLOR 143 

BLOAD 164 

BSAVE 165 

BYE 117 

CALL .229-230 

CASE_OF 87,172 

CAT$ 103 

CHAIN 227 

CHR$ 78 

CLEAR 71 

CLOSE 109 

COLOR 139 

COPY 104,226 

COS 75 

CREATE 105 

DATA 89,225 

DATE$ 82 

DECLARE 133 



DELAY 95 

DELETE 105 

DIALOG 172,206 

DIM 65 

DO 87 

DRAWSTR 145 

ELSE 84-85 

ELSEJDO 87 

END 109,116,157 

ENDCASE 87 

ENDDO 87 

ENDFUNC 131 

ENDPROC 132 

EOF 113 

EXP 72 

EXTEND 66 

FALSE 129 

FILE 110 

FLUSH 105 

FN 126, 133 

FOR 120 

FORMAT 105 

FRECO) 83 

FREEMEM 167 

FUNG 126,131 

GET 91,110 

GET_MEM 165 

GOSUB 125-126,132-133 

GOTO 53,119 

GR 139 

GS_OS 107 

HCOLOR 144 

HGR 143, 171 

HGR2 143,171 

HLIN 140 

HOME 95 

HPLOT 145 

HPLOTTO 145 

HTAB 100 

IF 84-85 

INCLUDE 136 

INDEX 79 

INKEY 92 

INPUT 92,111 

INSLOT 94 
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INSTRUM 152 

INT 56,72-73 

INVERSE 95 

LEFT$ 80 

LEN 78,145,200 

LET 70 

LINK J232 

LOCK 106 

LOG 73 

LONGINT 66 

LOWER$ 80 

LRETURN 231 

MENU 172,182 

MID$ 81 

MOD 67 

MOUSE 172,185, 

196,210 

MOV.MEM 167 

MS.TEXT 96 

MUSIC 150, 152, 156 

NEXT 121 

NOISE 150-151,156 

NORMAL 95-96 

NOTRACE 224 

ON...GOTO 119 

ON..GOSUB 135 

ONERRGOTO 53,169 

OPEN 112 

OUTSLOT 101 

PDL 148 

PEEK 162 

PERFORM 125,134 

PLOT 141 

POKE 162 

POP 134 

POS 99 

PREFIX 106 

PREFrX$ 82 

PRINT 96,112,222 

PRINT USING 97,112 

PROC 126, 132 

PROGRAM 49 

PRTON 100-101 

QUIET 151, 157 

READ 90 



REM 48 

RENAME 107 

REPEAT 124 

RESTORE 91 

RESUME 51,170,225 

RETURN . 125, 132 

RIGHT$ 81 

KND 158-159 

ROPEN 113 

ROUND 73 

ROUTINE 118,126-127 

RUN 116 

SCRN 141 

SEEK 114 

SEGMENT 229 

SGN 74 

SILENCE 151, 157 

SIN 75 

SPC 99 

SPEED 96 

SQR 74 

STOP 109, 117, 157, 222 

STR 56 

STR$ 78 

STRACE 223 

TAB 99 

TAN 75 

TEXT 102, 141, 171 

TIME$ 82 

TOOLBOX 212 

TRACE 222 

TRUE 129 

UNLOCK 107 

UNTIL 122, 124, 134 

UPPER$ 81 

VAL 78 

VALUE 130 

VLIN 141 

VTAB 100 

WAVE 160 

WEND 124 

WHILE 124 

WINDOW 11, 172, 188-191 

WOPEN 113 

Compiler Directives 
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Index 



ALIAS 49 

DECLARE 70 

INT 56,62-63 

STR 56,63-64 

Compiler Options 

BANKING 50,83 

CODE 41,50 

ERROR 51,170,225 

EXTEND 52,64,72,225 

LIST 52 

LONGINT 52,63,72, 

163,214,225 

NOGOTO 53 

NOT_C 53,93 

OPTIMIZ 54,223, 

225-226 

PRINTER 54 

VAR2 54 

COMPILER.SHELL . . . .5,236 

Concatenation 77 

Conditional statements . .84>85 

Control Panel 8 

Control Panel 8-9,39,54 

Control-C 39,53,93 

Control-S 93 

Controlled uncertainty . . .159, 161 

Table 160 

CONVERT 239 

COPY 19.104,226 

Copyright i 

COS 75 

CR 12 

CREATE 19 

D 

DATA 89,225 

Data entry 89-92 

Data output 96 

DATA Statement 

Order 49 

DATE$ 82 

Debugging 221,223-224, 

228 

Default prefix 106 

DELAY 95-96 



DELETE 19, 105 

Delete key 93 

Demo.Files 6 

DIALOG 172,206 

Dialog Box 

Checkbox 204 

Closure 206 

Control Number .... 206 

Creation 207 

Defiiung 206 

Dialog Control Number 206 

Displaying 209 

Edit line 205 

IDNumber 202 

Item type 203 

Monitoring 206 

Part addition ...... 209 

Partdisable 210 

PartEnable 209 

Part Removal 209 

Parts . 207 

Pushbutton 203 

Radio button 204 

Scrolbar ........ 204 

Staticline . 205 

Dialog Boxes 202 

DIM 66 

Direct page 233 

Directory 103 

Disk filing 109 

DO 87 

DOUBT 159 

DRAWSTR 145 

DUNNO 159 

£ 

EDIT 13,20,26 

Editor 2,5 

Apple key 28 

Apple-M 33 

Arrows 30 

Beginning of line ... 30 

Compilation firom . . . 35,42 

Control keys 27 

Control-B . 28 
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Control-X 28 

Control-Y 28 

Converting numbers . .37 

Copy text 32 

Delete character 28 

Delete key 29 

Delete text 32 

Deletion mode 28 

Down screen 30 

End of line 30 

Enter mode 29 

Entering the 26 

Esc key 28 

Find (backward) 33 

Find (forward) 33 

Goto line 31 

Help screen 29 

Insert file 34 

Load file 35 

LowerCase 29 

Move block 33 

Movement in 30 

New file 34 

Option key 28 

Overstrike mode 29 

Previous word 31 

Printing 36-37 

Quitting 26 

Relative motion 31 

Return key 28 

Saving a file 36 

Setting tabs 31 

SRC file 36 

Tabbing 32 

TXT files 36 

Up screen 30 

Uppercase 29 

Version number 37 

Editor Commands 

Apple-# 37 

Apple-? 29 

Apple-B 33 

Apple-C 30,32 

Apple-D 30,32 

Apple-Delete 28 



Apple-Digit 31 

Apple-Down Arrow . . 30 

Apple-E 29 

Apple-F 33 

Apple-G 31 

Apple-H 29 

Apple-I 34 

Apple-K 35,38,42 

Apple-L 35 

Apple-Left Arrow ... 30 

Apple-M 30 

Apple-N 34 

Apple-P 36 

Apple-Q 26 

Apple-Right Arrow , . 30 

Apple-S 36 

Apple-T 36 

Apple-Tab 31 

Apple-V 37 

Apple-W 37 

Apple-X 29 

Option- Left Arrow ... 31 

Option-Right Arrow . . 31 

ELSE 84-85 

ELSE_DO 87 

END 109,116,157 

ENDCASE 87 

EOF 113 

ERROR 51, 170, 225 

Trapping 169 

Error handling 168 

Example Programs 

CONTROLS 211 

Desktop. Samples . . . 173 

DIALOG 211 

Fractal generator ... 6 

LINKDEMO 233 

MABug.DEMO .... 6 

MENU 187 

WINDOW 188,200 

EXP 72 

Expr 11 

EXTEND 52,66,72 
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Index 



F 

Factorial 137 

FALSE 159 

FILE 110 

File Access Niitnber . . . .109 

Filename 11 

Files 

Deleting 105 

Lockiiig 106 

Random access 114 

Renaming 107 

Sequential 113 

Unlocking 107 

Filing Commands 104,106-107, 

109-110, 

112-113 

Find 33 

FLUSH 105 

FN 133 

Folder 

MicoLAdv.BASIC ... .5 

UTILITY 5,25 

FOR 120 

FOR...UNTIL 122 

FORMAT 20,105 

Formatted text output . . .97 

FRE(O) 83 

FREEMEM 167 

Functions 127-131 

G 

Game 6 

Garbage collection 82 

GET 91,110 

GET31EM 165 

Global Variables 128 

GOSUB 132-133 

GOTO 53,119 

Graphics 

Colors 139,144 

Low resolution 139-141 

Shapes 146 

Super High Resolution . 142-145 

GS/OS 1 

Accessing 107 



GS_OS 107 

H 

HardDisk 7,234 

Hardware 

Minimum requirements 6 

HCOLOR 144 

HELP 12,21,29 

Hezadedmal numbers , . 68 

HGR 143, 171 

HGR2 143,171 

High resolution graphics . 142 

HUN 140 

HOME 21,95 

HPLOT 145 

HPLOTTO 145 

HTAB 100 

I 

IF 84-85 

INCLUDE 136 

Indenter 25 

INDEX 79 

INFO.DOC i,6 

Information file i 

INKEY 92 

INPUT 92,111 

INSLOT 94 

ESrSTRUM 152 

INT 62,72-73 

Integers 

Long 52, 63 

Short 63 

INVERSE 95 

J 

Joystick , . . . 148 

K 

KompUe 38 

L 

Laser Printer 9 

LEFT$ . 80 
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LEN 78,145,200 

LET 70 

LIBRARY 5,44 

Library of routines 135 

Library routines 41 

Library.S.A 236 

Limit of Liability i 

Line Nximbers 46-47 

LINX 232 

The Linker 42 

LIST 21,52 

LoadPile 2,235 

Local variables 128 

LOCK 21,106 

LOG 73 

Lang integers 52 

LONGINT 52, 66, 72 

Loops 

FOR 120-121 

FOR.. .UNTIL 122 

Repeat 124 

WEND 124 

While 124 

LOWER$ 80 

LRETURN 231 

M 

MAB.SUPPORT i, 5, 25, 173, 

187-188,211, 

233-234, 

236-239 

MAB.TO.CDA folder . . . .238 
MAB.T0.S16 folder . . . .236 

MABug 198 

MAKE.CDA 238 

MAKE.SA.LNK 236 

Master Disk 5,234-236 

Memory 225 

Allocation 165, 167 

Memory Manager 44 

ID 165 

Memory Requirements . . .1 
MENU 172,182 

Attributes 176 
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